a64bd8c6671da03abdb9efd7ed5f7ee2b283d45c
\353\260\225\353\217\231\355\235\254.md
| ... | ... | @@ -18,4 +18,151 @@ https://dh8.kr |
| 18 | 18 | * 표에 대해서 셀 병합을 하려면 마크다운(?) 으로는 안된다고 하더라구요. 일단 마크다운형식으로 할수 있는 한 해봤습니다. 하고 나니 HTML형식으로 적어야 한다면 두번 일을 하게 되는 건가..고민 ㅠㅠ |
| 19 | 19 | * 넘버링은 찾아보니까 그냥 1,2,3 이렇게 쓰면 된다는 것 같은데 뭘 잘못했는지 계속 1,1,1 이렇게 넘어가는데, 혹시 넘버링 하는 것 알려주시면 헤더랑 같이 정리해두겠습니다. |
| 20 | 20 | |
| 21 | +--- |
|
| 22 | +layout: handbook-page-toc |
|
| 23 | +title: "Practical Handbook Edits Examples" |
|
| 24 | +description: "Video recordings and written tips for non-engineering team members on how to work Handbook-First" |
|
| 25 | +--- |
|
| 26 | +## On this page |
|
| 27 | +{:.no_toc .hidden-md .hidden-lg} |
|
| 28 | +- TOC |
|
| 29 | +{:toc .hidden-md .hidden-lg} |
|
| 30 | +## Welcome to the Practical Handbook Edits Examples Page |
|
| 31 | +This page contains video recordings and written tips for non-engineering team members on how to work Handbook-First. In these videos, we run through the GitLab Handbook with experts, uncovering how to best use the Handbook in our day-to-day work, and learning best-practices for Handbook editing along the way. This page is intended to be complementary to [Using GitLab at GitLab](/handbook/using-gitlab-at-gitlab/#using-gitlab-competency), and we suggest you start there if you have not yet completed the [GitLab 101 Tool Certification](/handbook/people-group/learning-and-development/certifications/gitlab-101/). |
|
| 32 | +**Have your own practical Handbook editing tips? Drop a video below!** |
|
| 33 | +### Creating new handbook pages and multimedia embedding best-practices |
|
| 34 | +<figure class="video_container"> |
|
| 35 | + <iframe src="https://www.youtube.com/embed/hQgS97M8abc" frameborder="0" allowfullscreen="true"> </iframe> |
|
| 36 | +</figure> |
|
| 37 | +**_Please note that the video mentions that you need to go to source/handbook to create a page which is no longer the case. The handbook is located under [sites/handbook/source/handbook](https://gitlab.com/gitlab-com/www-gitlab-com/-/tree/master/sites/handbook/source/handbook)_**. |
|
| 38 | +This video covers: |
|
| 39 | +- Creating a new handbook page - @:37 |
|
| 40 | +- Embedding a video - @15:25, @18:53 |
|
| 41 | +- Making a URL open in a new tab - @17:05 |
|
| 42 | +- How this page got started - @22:48 |
|
| 43 | +### Changing a page name and subsequent updates |
|
| 44 | +<figure class="video_container"> |
|
| 45 | + <iframe src="https://www.youtube.com/embed/HeQax_U74NM" frameborder="0" allowfullscreen="true"> </iframe> |
|
| 46 | +</figure> |
|
| 47 | +This video covers: |
|
| 48 | +- Renaming a URL - @1:05 |
|
| 49 | +- Redirecting from one URL to the other - @2:17 |
|
| 50 | +- Finding places where an old URL is linked and updating it to a new URL - @ 4:30 |
|
| 51 | +### Creating mermaid diagrams |
|
| 52 | +<figure class="video_container"> |
|
| 53 | + <iframe src="https://www.youtube.com/embed/SQ9QmuTHuSI" frameborder="0" allowfullscreen="true"> </iframe> |
|
| 54 | +</figure> |
|
| 55 | +This video covers: |
|
| 56 | +- Creating a mermaid diagram for the handbook: |
|
| 57 | + - Intro to a mermaid diagram |
|
| 58 | + - What they look like |
|
| 59 | + - Use cases for using them in the handbook |
|
| 60 | +### Creating issue templates |
|
| 61 | +<figure class="video_container"> |
|
| 62 | + <iframe src="https://www.youtube.com/embed/ObNWS3trqIY" frameborder="0" allowfullscreen="true"> </iframe> |
|
| 63 | +</figure> |
|
| 64 | +This video covers: |
|
| 65 | +- Why you may want to use issue templates - @0:10 |
|
| 66 | +- What is an issue template and how to create one - @:54 |
|
| 67 | +- How issue templates and boards facilitate workflow management and automation - @3:55 |
|
| 68 | +### Adding images to the handbook and handbook analytics |
|
| 69 | +<figure class="video_container"> |
|
| 70 | + <iframe src="https://www.youtube.com/embed/P7Nv7bzksiY" frameborder="0" allowfullscreen="true"> </iframe> |
|
| 71 | +</figure> |
|
| 72 | +This video covers: |
|
| 73 | +- How to see analytics on visits to a handbook page - @0:24 |
|
| 74 | +- When and how to add images to the handbook - @5:32 |
|
| 75 | +- How to keep up-to-date on changes in the handbook - @21:40 |
|
| 76 | + |
|
| 77 | +### How to add a new directory and page to the handbook |
|
| 78 | +<figure class="video_container"> |
|
| 79 | + <iframe src="https://www.youtube.com/embed/9NcJG9Bv6sQ" frameborder="0" allowfullscreen="true"> </iframe> |
|
| 80 | +</figure> |
|
| 81 | +This video covers: |
|
| 82 | +- How to add a new page to your section of the handbook complete with a new main page and table of contents |
|
| 83 | +### Updating individual team member YAML for managerial changes |
|
| 84 | +Every GitLab team member has an entry in [team_members/person](https://gitlab.com/gitlab-com/www-gitlab-com/-/tree/master/data/team_members/person) and when a new manager joins a team, updates are needed in three places: |
|
| 85 | +- Manager's entry - Update job family |
|
| 86 | +- Team member's entry - Update `reports_to` to include the new manager slug |
|
| 87 | +- [`stages.yml`](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/stages.yml) to indicate the new manager for the team (if part of engineering/product) |
|
| 88 | +Find step by step instructions on how to update the individual YAMLs in the [Edit this website locally handbook page](https://about.gitlab.com/handbook/git-page-update/#11-add-yourself-to-the-team-page) |
|
| 89 | +### More Tips |
|
| 90 | +#### Pre-requisites |
|
| 91 | +Some tips may require terminal shell access on macOS/Linux. Ensure that your environment is working and that you have cloned the [www-gitlab-com](https://gitlab.com/gitlab-com/www-gitlab-com) project for example. |
|
| 92 | +``` |
|
| 93 | +git clone https://gitlab.com/gitlab-com/www-gitlab-com.git |
|
| 94 | +``` |
|
| 95 | +Sync it. Ensure that you stash away local changed not yet committed. |
|
| 96 | +``` |
|
| 97 | +cd www-gitlab-com |
|
| 98 | +git stash |
|
| 99 | +git checkout master |
|
| 100 | +git pull |
|
| 101 | +``` |
|
| 102 | +On macOS it is advised to use Homebrew and install the GNU tools. See [this blogpost](https://about.gitlab.com/blog/2020/04/17/dotfiles-document-and-automate-your-macbook-setup/) for a macOS setup. |
|
| 103 | +``` |
|
| 104 | +brew install gnu-sed |
|
| 105 | +``` |
|
| 106 | +#### Find files |
|
| 107 | +One of the shell tools provided with macOS/Linux GNU is `find`. Open a terminal an run the following command in the main directory of the `www-gitlab-com` repository to get a list of all `*.md` files. This matches `.md` as suffix. |
|
| 108 | +``` |
|
| 109 | +find . -type f -name '*.md' |
|
| 110 | +``` |
|
| 111 | +Instead of the `.` you can also use a directory in the current path. |
|
| 112 | +``` |
|
| 113 | +find source/handbook -type f -name '*.md' |
|
| 114 | +``` |
|
| 115 | +The type `f` specifies files, `d` matches for directories. When not specified, all files and directories are taken into account. |
|
| 116 | +You can replace `-name` with `-regex` to do more sensitive matching, for example to match all `.md` and `.md.erb` files. |
|
| 117 | +``` |
|
| 118 | +find . -type f -regex '.*\.md[.erb]*' |
|
| 119 | +``` |
|
| 120 | +This can be useful to **check whether a blog post was merged to master**: |
|
| 121 | +``` |
|
| 122 | +git checkout master |
|
| 123 | +git pull |
|
| 124 | +find . -type f -name '*blogpost-filename*' |
|
| 125 | +``` |
|
| 126 | +#### Find files and perform an action |
|
| 127 | +This comes in handy when you want to print all matches with a prefix, or perform additional replace actions. The main principle is to follow the matching rules explained above, and add the `-exec` parameter. |
|
| 128 | +The `exec` action should start a shell and execute a command in there. `sh -c '' \;` takes care of this for every file that matches. Imagine this as a loop of sequential steps to perform the action. The last missing bit is accessing the file in the current loop iteration. This is done via the `{}` marker inside the `echo` example printing the output. |
|
| 129 | +Run the command in a terminal to see how it works: |
|
| 130 | +``` |
|
| 131 | +find source/handbook/marketing -type f -name '*.md' -exec sh -c 'echo "Matched {}"' \; |
|
| 132 | +``` |
|
| 133 | +#### Replace strings in a file |
|
| 134 | +The GNU `sed` shell command is useful to replace a defined string in a file. The `-i` flag specifies to do that inline in the same file. The `g` flag defines a global match, replacing all pattern matches. |
|
| 135 | +``` |
|
| 136 | +sed -i 's/<searchtext>/<replacementtext>/g' file.md |
|
| 137 | +``` |
|
| 138 | +On macOS, ensure that the `gnu-sed` package is installed, and run `gsed` (instead of `sed`). |
|
| 139 | +``` |
|
| 140 | +gsed -i 's/<searchtext>/<replacementtext>/g' file.md |
|
| 141 | +``` |
|
| 142 | +With using the `/` separator, it is necessary to escape all `/` characters in the string. You can avoid this by choosing another separator, for example `,`: |
|
| 143 | +``` |
|
| 144 | +gsed -i 's,<searchtext>,<replacementtext>,g' file.md |
|
| 145 | +``` |
|
| 146 | +#### Find and Replace a String in all (Matching) Files |
|
| 147 | +Sometimes a project, URL target or Slack channel is being renamed. You can easily search and edit with the Web IDE on GitLab.com but for other files there is a quick and automated way required. |
|
| 148 | +This method combines the find, exec and sed tips explained above. The `exec` action is now to use sed to perform an inline replacement of a pattern/string. |
|
| 149 | +The following example is used in [this MR](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/49617) for updating the Corporate Marketing project URL in all files. |
|
| 150 | +``` |
|
| 151 | +git checkout master |
|
| 152 | +git pull origin master |
|
| 153 | +git checkout -b handbook/corp-mktg-project-url |
|
| 154 | +find source/handbook -type f -exec sh -c 'gsed -i "s,https://gitlab.com/gitlab-com/marketing/corporate-marketing,https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing,g" "{}"' \; |
|
| 155 | +git status |
|
| 156 | +git diff |
|
| 157 | +git commit -av -m "Handbook: Update corporate marketing project URL" |
|
| 158 | +git push -u origin handbook/corp-mktg-project-url |
|
| 159 | +<open URL in browser for MR> |
|
| 160 | +``` |
|
| 161 | +To cut it down: |
|
| 162 | +- Find and match all files in the `source/handbook` directory. The URL might be found in other files too. |
|
| 163 | +- `exec` runs a `sed/gsed` action |
|
| 164 | +- The replacement is `https://gitlab.com/gitlab-com/marketing/corporate-marketing` with `https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing` |
|
| 165 | +- Verify the changes with `git status` and `git diff` before committing them |
|
| 166 | +- Commit, push and create the MR from the URL |
|
| 167 | + |
|
| 21 | 168 | |
| ... | ... | \ No newline at end of file |
