# Practical Handbook Edits Examples

1. You are here:
2. [Handbook](https://zahorecz-tibor.gitbook.io/product-management/untitled-4/broken-reference)
3. Practical Handbook Edits Examples

## On this page <a href="#on-this-page" id="on-this-page"></a>

## Welcome to the Practical Handbook Edits Examples Page <a href="#welcome-to-the-practical-handbook-edits-examples-page" id="welcome-to-the-practical-handbook-edits-examples-page"></a>

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](https://about.gitlab.com/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](https://about.gitlab.com/handbook/people-group/learning-and-development/certifications/gitlab-101/).

Have your own practical Handbook editing tips? Drop a video below!

### Creating new handbook pages and multimedia embedding best-practices <a href="#creating-new-handbook-pages-and-multimedia-embedding-best-practices" id="creating-new-handbook-pages-and-multimedia-embedding-best-practices"></a>

***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).

This video covers:

* Creating a new handbook page - @:37
* Embedding a video - @15:25, @18:53
* Making a URL open in a new tab - @17:05
* How this page got started - @22:48

### Changing a page name and subsequent updates <a href="#changing-a-page-name-and-subsequent-updates" id="changing-a-page-name-and-subsequent-updates"></a>

This video covers:

* Renaming a URL - @1:05
* Redirecting from one URL to the other - @2:17
* Finding places where an old URL is linked and updating it to a new URL - @ 4:30

### Creating mermaid diagrams <a href="#creating-mermaid-diagrams" id="creating-mermaid-diagrams"></a>

This video covers:

* Creating a mermaid diagram for the handbook:
  * Intro to a mermaid diagram
  * What they look like
  * Use cases for using them in the handbook

### Creating issue templates <a href="#creating-issue-templates" id="creating-issue-templates"></a>

This video covers:

* Why you may want to use issue templates - @0:10
* What is an issue template and how to create one - @:54
* How issue templates and boards facilitate workflow management and automation - @3:55

### Adding images to the handbook and handbook analytics <a href="#adding-images-to-the-handbook-and-handbook-analytics" id="adding-images-to-the-handbook-and-handbook-analytics"></a>

This video covers:

* How to see analytics on visits to a handbook page - @0:24
* When and how to add images to the handbook - @5:32
* How to keep up-to-date on changes in the handbook - @21:40

### How to add a new directory and page to the handbook <a href="#how-to-add-a-new-directory-and-page-to-the-handbook" id="how-to-add-a-new-directory-and-page-to-the-handbook"></a>

This video covers:

* How to add a new page to your section of the handbook complete with a new main page and table of contents

### More Tips <a href="#more-tips" id="more-tips"></a>

#### Pre-requisites <a href="#pre-requisites" id="pre-requisites"></a>

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.

```
git clone https://gitlab.com/gitlab-com/www-gitlab-com.git
```

Sync it. Ensure that you stash away local changed not yet committed.

```
cd www-gitlab-com
git stash
git checkout master
git pull
```

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.

#### Find files <a href="#find-files" id="find-files"></a>

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.

```
find . -type f -name '*.md'
```

Instead of the `.` you can also use a directory in the current path.

```
find source/handbook -type f -name '*.md'
```

The type `f` specifies files, `d` matches for directories. When not specified, all files and directories are taken into account.

You can replace `-name` with `-regex` to do more sensitive matching, for example to match all `.md` and `.md.erb` files.

```
find . -type f -regex '.*\.md[.erb]*'
```

This can be useful to **check whether a blog post was merged to master**:

```
git checkout master
git pull
find . -type f -name '*blogpost-filename*'
```

#### Find files and perform an action <a href="#find-files-and-perform-an-action" id="find-files-and-perform-an-action"></a>

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.

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.

Run the command in a terminal to see how it works:

```
find source/handbook/marketing -type f -name '*.md' -exec sh -c 'echo "Matched {}"' \;
```

#### Replace strings in a file <a href="#replace-strings-in-a-file" id="replace-strings-in-a-file"></a>

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.

On macOS, ensure that the `gnu-sed` package is installed, and run `gsed` (instead of `sed`).

With using the `/` separator, it is necessary to escape all `/` characters in the string. You can avoid this by choosing another separator, for example `,`:

#### Find and Replace a String in all (Matching) Files <a href="#find-and-replace-a-string-in-all-matching-files" id="find-and-replace-a-string-in-all-matching-files"></a>

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.

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.

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.

```
git checkout master
git pull origin master

git checkout -b handbook/corp-mktg-project-url

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" "{}"' \;

git status
git diff

git commit -av -m "Handbook: Update corporate marketing project URL"

git push -u origin handbook/corp-mktg-project-url


```

To cut it down:

* Find and match all files in the `source/handbook` directory. The URL might be found in other files too.
* `exec` runs a `sed/gsed` action
* The replacement is `https://gitlab.com/gitlab-com/marketing/corporate-marketing` with `https://gitlab.com/gitlab-com/marketing/corporate_marketing/corporate-marketing`
* Verify the changes with `git status` and `git diff` before committing them
* Commit, push and create the MR from the URL