README.md 16.2 KB
Newer Older
Evan Read's avatar
Evan Read committed
1
# GitLab documentation
Connor Shea's avatar
Connor Shea committed
2

Evan Read's avatar
Evan Read committed
3 4
[![build status](https://gitlab.com/gitlab-org/gitlab-docs/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-docs/commits/master)

Evan Read's avatar
Evan Read committed
5 6 7
This project hosts the repository used to generate the GitLab documentation
website and deployed to [https://docs.gitlab.com](https://docs.gitlab.com). It
uses the [Nanoc](http://nanoc.ws) static site generator.
Connor Shea's avatar
Connor Shea committed
8

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
9
You will not find any GitLab docs content here. All documentation files are
Achilleas Pipinellis's avatar
Fix URL  
Achilleas Pipinellis committed
10
hosted in the respective repository of [each product](#projects-we-pull-from).
Achilleas Pipinellis's avatar
Add ToC  
Achilleas Pipinellis committed
11

Evan Read's avatar
Evan Read committed
12
The [deployment process](#deployment-process) happens automatically every four hours.
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
13

14 15 16 17 18 19 20 21 22
## Contributing agreement

Read [CONTRIBUTING.md](CONTRIBUTING.md) for an overview of the Developer
Certificate of Origin + License.

## License

See [LICENSE](LICENSE).

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
23
## Projects we pull from
24

25
There are currently 4 products that are pulled and generate the docs website:
26

27
- [GitLab](https://gitlab.com/gitlab-org/gitlab)
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
28 29
- [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab)
- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner)
30
- [GitLab Chart](https://gitlab.com/gitlab-org/charts/gitlab)
31

32
**Note:**
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
33
Although GitLab Community Edition is generated, it is hidden from the website
34 35 36
as it's the same as the Enterprise Edition. We generate it for consistency,
until [better redirects](https://gitlab.com/gitlab-org/gitlab-pages/issues/24)
are implemented.
37

38
## Requirements
39

40 41
In order to be able to preview any changes you make to GitLab's documentation,
here's what you will need to have:
42

Evan Read's avatar
Evan Read committed
43 44
- Environment: Unix/Linux or macOS.
- Ruby 2.6.6.
45
- Node.js (latest LTS).
Evan Read's avatar
Evan Read committed
46 47 48 49
- Yarn (latest version).
- Xcode *(macOS only)*:
  - Run `xcode-select --install` to install the command line tools only.
  - Or download and install the entire package using the macOS's App Store.
50

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
51 52 53
**Note:**
On Windows, the process described here would be different, but as most of
contributors use Unix, we'll go over this process for macOS and Linux users.
54

55
## Install dependencies
56

57
There are a couple of options for installing dependencies for `gitlab-docs`:
58

59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
- Using [separate dependency managers](#use-separate-dependency-managers) for Ruby, Node.js, and
  Yarn.
- The [unified dependency manager](#use-asdf) `asdf` for Ruby, Node.js, and Yarn.

The choice of which to use will depend on what you currently use. If you don't yet have Ruby,
Node.js, and Yarn set up, use [`asdf`](https://asdf-vm.com/#/).

### Use separate dependency managers

In the instructions below, you:

- Install Ruby using `rbenv`.
- Install Node.js using `nvm`.
- Install Yarn using your preferred method in their installation instructions.

#### Ruby

To install Ruby using [rbenv](https://github.com/rbenv/rbenv):
77

Evan Read's avatar
Evan Read committed
78
1. [Install rbenv](https://github.com/rbenv/rbenv#installation).
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
79
1. Install the latest Ruby:
80

81
   ```shell
Evan Read's avatar
Evan Read committed
82
   rbenv install 2.6.6
83
   ```
84

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
85
1. Use the newly installed Ruby:
86

87
   ```shell
Evan Read's avatar
Evan Read committed
88
   rbenv global 2.6.6
89
   ```
90

Evan Read's avatar
Evan Read committed
91 92 93 94
Check your:

- Ruby version with `ruby --version`.
- Bundler version with `bundle --version`. You need version 1.17.3.
Connor Shea's avatar
Connor Shea committed
95

96
#### Node.js
Jacques Erasmus's avatar
Jacques Erasmus committed
97

98
To install Node.js using [nvm](https://github.com/nvm-sh/nvm):
Jacques Erasmus's avatar
Jacques Erasmus committed
99

100 101
1. [Install nvm](https://github.com/nvm-sh/nvm#installation-and-update).
1. Install the latest Node.js:
Jacques Erasmus's avatar
Jacques Erasmus committed
102

103
   ```shell
Evan Read's avatar
Evan Read committed
104
   nvm install --lts
105
   ```
Jacques Erasmus's avatar
Jacques Erasmus committed
106

107
1. Use the newly installed Node.js:
Jacques Erasmus's avatar
Jacques Erasmus committed
108

109
   ```shell
Evan Read's avatar
Evan Read committed
110
   nvm use --lts --default
111
   ```
Jacques Erasmus's avatar
Jacques Erasmus committed
112

113
Check your Node.js version with `node -v`.
Jacques Erasmus's avatar
Jacques Erasmus committed
114

115
#### Yarn
Jacques Erasmus's avatar
Jacques Erasmus committed
116

Evan Read's avatar
Evan Read committed
117
Install [yarn](https://yarnpkg.com/en/docs/install), a package manager for the
118
Node.js ecosystem.
Jacques Erasmus's avatar
Jacques Erasmus committed
119 120 121

Check your Yarn version with `yarn -v`.

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156
### Use `asdf`

To install Ruby, Node.js, and Yarn using `asdf`:

1. [Install `asdf`](https://asdf-vm.com/#/core-manage-asdf-vm?id=install).
1. Add the Ruby, Node.js, and Yarn [`asdf` plugins](https://asdf-vm.com/#/core-manage-plugins)
   required to install versions of these dependencies:

   ```shell
   asdf plugin add ruby
   asdf plugin add nodejs
   asdf plugin add yarn
   ```

1. [Install](https://asdf-vm.com/#/core-manage-versions) the dependencies listed in the project's
   `.tool-versions` file:

   ```shell
   asdf install
   ```

1. Set the installed versions of Ruby, Node.js, and Yarn to be global for projects that don't use
   `.tool-versions` files. For example to set Ruby 2.6.6 as the global default, run:

   ```shell
   asdf global ruby 2.6.6
   ```

Check your:

- Ruby version with `ruby --version`.
- Bundler version with `bundle --version`. You need version 1.17.3.
- Node.js version with `node -v`.
- Yarn version with `yarn -v`

157 158
## Install Nanoc's dependencies

159
The project depends on many Ruby and Node.js libraries. To install these:
160

Evan Read's avatar
Evan Read committed
161
1. Open a terminal and navigate to your local checkout of this project.
162 163
1. Run:

164
   ```shell
Evan Read's avatar
Evan Read committed
165
   bundle install && yarn install --frozen-lockfile
166
   ```
167 168 169 170

## Development when contributing to GitLab documentation

This section is about contributing to one of GitLab's
171
[projects' documentation](#projects-we-pull-from), and preview your changes at
Evan Read's avatar
Evan Read committed
172
the same time. To contribute to the appearance of the documentation site, see
173
[contributing to the docs site](#contributing-to-the-docs-website-itself).
174 175 176

Before diving into writing, here's a few links that will come in handy:

177 178
- [Writing documentation](https://docs.gitlab.com/ee/development/documentation/index.html)
- [Style guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html)
179 180

### Clone the repositories
Connor Shea's avatar
Connor Shea committed
181

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
182
Since this process will clone a few repositories, it might be a good idea to
Evan Read's avatar
Evan Read committed
183 184
create a separate directory to have them all together. For example, to store all
local checkouts in a `dev` directory:
185

Evan Read's avatar
Evan Read committed
186
1. Open a terminal and run:
187

188
   ```shell
Evan Read's avatar
Evan Read committed
189
   mkdir -p ~/dev/
190
   ```
191

Evan Read's avatar
Evan Read committed
192
1. Navigate to the directory you'd like the repositories to be cloned:
193

194
   ```shell
Evan Read's avatar
Evan Read committed
195
   cd ~/dev
196
   ```
197

Evan Read's avatar
Evan Read committed
198
1. Clone the documentation's website repository:
199

200
   ```shell
Evan Read's avatar
Evan Read committed
201 202
   ## Using SSH (for GitLab Team members)
   git clone [email protected]:gitlab-org/gitlab-docs.git
203

Evan Read's avatar
Evan Read committed
204 205
   ## Using HTTPS (for external contributors)
   git clone https://gitlab.com/gitlab-org/gitlab-docs.git
206
   ```
207

Evan Read's avatar
Evan Read committed
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
1. Clone the repositories you wish to contribute documentation changes to. For:
   - **GitLab contributors** that don't have Developer access to the projects,
     fork the ones you want and then clone them by using your forked version:

     ```shell
     ## Using HTTPS (for members that do not have Developer access)
     git clone https://gitlab.com/<username>/gitlab.git
     git clone https://gitlab.com/<username>/gitlab-runner.git
     git clone https://gitlab.com/<username>/omnibus-gitlab.git
     git clone https://gitlab.com/<username>/gitlab.git charts
     ```

   - For members that have Developer access (usually the
     **GitLab Team members**), clone the required repos using SSH:

     ```shell
     ## Using SSH (for members that have Developer access)
     git clone [email protected]:gitlab-org/gitlab.git
     git clone [email protected]:gitlab-org/gitlab-runner.git
     git clone [email protected]:gitlab-org/omnibus-gitlab.git
     git clone [email protected]:gitlab-org/charts/gitlab.git charts
     ```

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
231
### Create the content symlinks
Connor Shea's avatar
Connor Shea committed
232

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
233
Nanoc expects the Markdown files to be under `content/<slug>`, where `<slug>`
Evan Read's avatar
Evan Read committed
234
is the slug of each product as defined in [`.nanoc.yaml`](nanoc.yaml).
235

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
236 237 238
If you have already cloned the repository (or repositories) you want to
contribute to, you can easily satisfy Nanoc's requirement by symlinking only
the directory that holds the documentation content.
239

Evan Read's avatar
Evan Read committed
240
1. Open a terminal and navigate to the directory where `gitlab-docs` was cloned.
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
241
1. For each one of the products, create the symlink:
242

243
   ```shell
Evan Read's avatar
Evan Read committed
244 245 246 247
   ln -s ~/dev/gitlab/doc ~/dev/gitlab-docs/content/ee
   ln -s ~/dev/omnibus-gitlab/doc ~/dev/gitlab-docs/content/omnibus
   ln -s ~/dev/gitlab-runner/docs ~/dev/gitlab-docs/content/runner
   ln -s ~/dev/charts/doc ~/dev/gitlab-docs/content/charts
248
   ```
249

Marcin Sedlak-Jakubowski's avatar
Marcin Sedlak-Jakubowski committed
250
1. Check if the symlinks were successfully created:
251

252
   ```shell
Evan Read's avatar
Evan Read committed
253
   cd dev/gitlab-docs
254 255
   ls -la content/
   ```
256

Mike Jang's avatar
Mike Jang committed
257
If they're there, we're almost good to go!
258

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
259 260 261
**Note:** You can use the `pwd` command when in the terminal to check the
directory path you are currently in and use that output to use with the symlinks
commands above.
262

Evan Read's avatar
Evan Read committed
263
## Preview the documentation website
Mike Jang's avatar
Mike Jang committed
264

Evan Read's avatar
Evan Read committed
265 266
Run the following command to build the documentation site and bring the embedded
web server up:
267

268
```shell
Evan Read's avatar
Evan Read committed
269
bundle exec nanoc && bundle exec nanoc live
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
270
```
271

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
272
This will generate and the site and you will be able to view it in your browser
Evan Read's avatar
Evan Read committed
273
at <http://localhost:3000>.
274

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
275
To preview the site on another port, use:
276

277
```shell
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
278 279
bundle exec nanoc live -p 3004
```
280

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
281 282
This will generate and the site and you will be able to view it in your browser
at <http://localhost:3004>.
283

Marcia Ramos's avatar
Marcia Ramos committed
284 285 286 287 288 289 290 291
### Recompile documentation changes

Due to a [bug on **macOS**](https://gitlab.com/gitlab-org/gitlab-docs/-/issues/81),
every time you change a file in the documentation (in one
of the repos: GitLab, Omnibus, Runner, or Charts), you'll need to recompile the site
to preview your changes:

```shell
Evan Read's avatar
Evan Read committed
292
bundle exec nanoc && bundle exec nanoc live
Marcia Ramos's avatar
Marcia Ramos committed
293 294 295 296
```

It recompiles incrementally, only updating the recently changed files.

Evan Read's avatar
Evan Read committed
297
### Preview on mobile
Marcia Ramos's avatar
Marcia Ramos committed
298

Evan Read's avatar
Evan Read committed
299
If you want to check how your changes look on mobile devices, you can use:
Marcia Ramos's avatar
Marcia Ramos committed
300

Evan Read's avatar
Evan Read committed
301 302 303 304 305 306
- [Responsive Design Mode](https://support.apple.com/en-au/guide/safari-developer/dev84bd42758/mac)
  on Safari.
- [Responsive Design Mode](https://developer.mozilla.org/en-US/docs/Tools/Responsive_Design_Mode)
  on Firefox.
- [Device Mode](https://developers.google.com/web/tools/chrome-devtools/device-mode)
  on Chrome.
307

Evan Read's avatar
Evan Read committed
308 309
An alternative is to preview the documentation site with your own devices, as
long as they are connected to the same network as your computer.
310

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
311 312 313
To do that, we need to change the IP address Nanoc is serving on from the
default `http://127.0.0.1` to your computer's
[private IPv4 address](https://www.howtogeek.com/236838/how-to-find-any-devices-ip-address-mac-address-and-other-network-connection-details/).
314

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
315 316
Once you know what's your computer's private IPv4, use the flag `-o`. For
example, let's say your current IPv4 address is `192.168.0.105`:
317

318
```shell
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
319 320
bundle exec nanoc live -o 192.168.0.105
```
321

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
322 323 324
Now, open your mobile's browser and type `http://192.168.0.105:3000`, and you should
be able to navigate through the docs site. This process applies to previewing the
docs site on every device connected to your network.
325

326 327
### Preview on the GitLab Development Kit

Evan Read's avatar
Evan Read committed
328 329 330
Alternatively, you can preview changes using the GitLab Development Kit (GDK).
For more information, see [Setting up GitLab Docs](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md)
in the GDK repository.
331

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
332
## Contributing to the docs website itself
333

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
334
If you want to just contribute to the docs website, and not the content, you
Evan Read's avatar
Evan Read committed
335
can use the following command to automatically pull the documentation content
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
336
to have something to preview:
337

338
```shell
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
339 340
bundle exec rake pull_repos
```
341

Evan Read's avatar
Evan Read committed
342 343
This will download all the documentation content under the `tmp/` directory and
copy it in `content/`. You can then [preview the website](#preview-the-docs-website).
344

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
345 346
If you want to force-delete the `tmp/` and `content/` folders so the task will
run without manual intervention, run:
347

348
```shell
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
349 350
RAKE_FORCE_DELETE=true rake pull_repos
```
351

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383
## Using YAML data files

The easiest way to achieve something similar to
[Jekyll's data files](https://jekyllrb.com/docs/datafiles/) in Nanoc is by
using the [`@items`](https://nanoc.ws/doc/reference/variables/#items-and-layouts)
variable.

The data file must be placed inside the `content/` directory and then it can
be referenced in an ERB template.

Suppose we have the `content/_data/versions.yaml` file with the content:

```yaml
versions:
- 10.6
- 10.5
- 10.4
```

We can then loop over the `versions` array with something like:

```erb
<% @items['/_data/versions.yaml'][:versions].each do | version | %>

<h3><%= version %></h3>

<% end &>
```

Note that the data file must have the `yaml` extension (not `yml`) and that
we reference the array with a symbol (`:versions`).

Jacques Erasmus's avatar
Jacques Erasmus committed
384 385
## Modern JavaScript

Evan Read's avatar
Evan Read committed
386 387
A lot of the JavaScript can be found in [content/assets/javascripts/](/content/assets/javascripts).
The files in this directory are handcrafted `ES5` JavaScript files.
Evan Read's avatar
Evan Read committed
388

Evan Read's avatar
Evan Read committed
389 390 391
We've [recently introduced](https://gitlab.com/gitlab-org/gitlab-docs/merge_requests/577)
the ability to write modern JavaScript. All modern JavaScript should be added to
the [content/frontend/](/content/frontend) directory.
Jacques Erasmus's avatar
Jacques Erasmus committed
392 393 394

### Adding a new bundle

Evan Read's avatar
Evan Read committed
395
When adding a new bundle, the layout name (`html`) and bundle name (`js`) should
Jacques Erasmus's avatar
Jacques Erasmus committed
396 397
match to make it easier to find:

Evan Read's avatar
Evan Read committed
398
1. Add the new bundle to `content/frontend/<bundle-name>/<bundle-name>.js`.
Jacques Erasmus's avatar
Jacques Erasmus committed
399 400 401
1. Import the bundle in the html file `layouts/<bundle-name>.html`:

   ```html
402
   <script src="<%= @items['/frontend/<bundle-name>/<bundle-name>.*'].path %>"></script>
Jacques Erasmus's avatar
Jacques Erasmus committed
403 404 405
   ```

You should replace `<bundle-name>` with whatever you'd like to call your
Evan Read's avatar
Evan Read committed
406
bundle.
Jacques Erasmus's avatar
Jacques Erasmus committed
407 408

## Bumping versions of CSS and JavaScript
409

Jacques Erasmus's avatar
Jacques Erasmus committed
410
Whenever the custom CSS and JavaScript files under `content/assets/` change,
411 412
make sure to bump their version in the frontmatter. This method guarantees that
your changes will take effect by clearing the cache of previous files.
413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431

Always use Nanoc's way of including those files, do not hardcode them in the
layouts. For example use:

```erb
<script async type="application/javascript" src="<%= @items['/assets/javascripts/badges.*'].path %>"></script>

<link rel="stylesheet" href="<%= @items['/assets/stylesheets/toc.*'].path %>">
```

The links pointing to the files should be similar to:

```erb
<%= @items['/path/to/assets/file.*'].path %>
```

Nanoc will then build and render those links correctly according with what's
defined in [`Rules`](/Rules).

432 433 434 435 436 437
## Linking to source files

A helper called [`edit_on_gitlab`](/lib/helpers/edit_on_gitlab.rb) can be used
to link to a page's source file. We can link to both the simple editor and the
web IDE. Here's how you can use it in a Nanoc layout:

Evan Read's avatar
Evan Read committed
438 439
- Default editor:
  `<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>`
440 441 442 443
- Web IDE: `<a href="<%= edit_on_gitlab(@item, editor: :webide) %>">Web IDE</a>`

If you don't specify `editor:`, the simple one is used by default.

444 445
## Review Apps for documentation merge requests

446 447
If you are contributing to GitLab docs read how to [create a Review App with each
merge request](https://docs.gitlab.com/ee/development/documentation/index.html#previewing-the-changes-live).
448

449 450
## Deployment process

Evan Read's avatar
Evan Read committed
451 452
We use [GitLab Pages](https://about.gitlab.com/features/pages/) to build and
host this website. See [`.gitlab-ci.yml`](.gitlab-ci.yml) for more information.
453

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
454
We also use [scheduled pipelines](https://docs.gitlab.com/ee/user/project/pipelines/schedules.html)
Evan Read's avatar
Evan Read committed
455
to build the site once every four hours.
456

457 458
By default, we pull from the master branch of [all the projects](#projects-we-pull-from).

459 460 461 462 463 464 465 466 467 468 469 470 471 472 473
## Algolia search

The docs site uses [Algolia docsearch](https://community.algolia.com/docsearch/)
for its search function. This is how it works:

1. GitLab is a member of the [docsearch program](https://community.algolia.com/docsearch/#join-docsearch-program),
   which is the free tier of [Algolia](https://www.algolia.com/).
1. Algolia hosts a [doscsearch config](https://github.com/algolia/docsearch-configs/blob/master/configs/gitlab.json)
   for the GitLab docs site, and we've worked together to refine it.
1. That [config](https://community.algolia.com/docsearch/config-file.html) is
   parsed by their [crawler](https://community.algolia.com/docsearch/crawler-overview.html)
   every 24h and [stores](https://community.algolia.com/docsearch/inside-the-engine.html)
   the [docsearch index](https://community.algolia.com/docsearch/how-do-we-build-an-index.html)
   on [Algolia's servers](https://community.algolia.com/docsearch/faq.html#where-is-my-data-hosted%3F).
1. On the docs side, we use a [docsearch layout](/layouts/docsearch.html) which
Evan Read's avatar
Evan Read committed
474
   is present on pretty much every page except <https://docs.gitlab.com/search/>,
475
   which uses its [own layout](/layouts/instantsearch.html). In those layouts,
476
   there's a Javascript snippet which initiates docsearch by using an API key
477 478 479 480 481 482 483 484
   and an index name (`gitlab`) that are needed for Algolia to show the results.

**For GitLab employees:**
The credentials to access the Algolia dashboard are stored in 1Password. If you
want to receive weekly reports of the search usage, search the Google doc with
title "Email, Slack, and GitLab Groups and Aliases", search for `docsearch`,
and add a comment with your email to be added to the alias that gets the weekly
reports.