Practical Handbook Edits Examples
Was this helpful?
Was this helpful?
You are here:
Handbook
Practical Handbook Edits Examples
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 , and we suggest you start there if you have not yet completed the .
Have your own practical Handbook editing tips? Drop a video below!
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 .
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
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
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
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
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
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
Sync it. Ensure that you stash away local changed not yet committed.
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.
Instead of the .
you can also use a directory in the current path.
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.
This can be useful to check whether a blog post was merged to master:
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:
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 ,
:
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.
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
Some tips may require terminal shell access on macOS/Linux. Ensure that your environment is working and that you have cloned the project for example.
On macOS it is advised to use Homebrew and install the GNU tools. See for a macOS setup.
The following example is used in for updating the Corporate Marketing project URL in all files.