diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 253 |
1 files changed, 106 insertions, 147 deletions
@@ -1,39 +1,15 @@ -# GitLab Documentation +# GitLab documentation [![build status](https://gitlab.com/gitlab-org/gitlab-docs/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-docs/commits/master) -This project hosts the repository used to generate the GitLab -documentation website and deployed to https://docs.gitlab.com. It uses the -[Nanoc](http://nanoc.ws) static site generator. +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. You will not find any GitLab docs content here. All documentation files are hosted in the respective repository of [each product](#projects-we-pull-from). -The [deployment process](#deployment-process) happens automatically every hour. - -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> -**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* - -- [Contributing agreement](#contributing-agreement) -- [License](#license) -- [Projects we pull from](#projects-we-pull-from) -- [Requirements](#requirements) - - [Ruby](#ruby) -- [Install Nanoc's dependencies](#install-nanocs-dependencies) -- [Development under GDK](#development-under-gdk) -- [Development when contributing to GitLab documentation](#development-when-contributing-to-gitlab-documentation) - - [Clone the repositories](#clone-the-repositories) - - [Create the content symlinks](#create-the-content-symlinks) -- [Preview the Docs website](#preview-the-docs-website) - - [Preview on mobile](#preview-on-mobile) -- [Contributing to the docs website itself](#contributing-to-the-docs-website-itself) -- [Using YAML data files](#using-yaml-data-files) -- [Review Apps for documentation merge requests](#review-apps-for-documentation-merge-requests) -- [Deployment process](#deployment-process) -- [Algolia search](#algolia-search) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> +The [deployment process](#deployment-process) happens automatically every four hours. ## Contributing agreement @@ -64,12 +40,13 @@ are implemented. In order to be able to preview any changes you make to GitLab's documentation, here's what you will need to have: -- Environment: Unix/Linux or macOS -- Ruby 2.6 or greater -- Node -- Yarn -- Xcode *(macOS only)*: Run `xcode-select --install` to install the command line tools only, - or, alternativelly, download and install the entire package using the macOS's App Store. +- Environment: Unix/Linux or macOS. +- Ruby 2.6.6. +- Node (latest LTS). +- 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. **Note:** On Windows, the process described here would be different, but as most of @@ -80,162 +57,152 @@ contributors use Unix, we'll go over this process for macOS and Linux users. The recommended way is to use a Ruby version manager to install Ruby in your system. -One way is to use RVM: +We recommend [rbenv](https://github.com/rbenv/rbenv): -1. [Install RVM](https://rvm.io/rvm/install) +1. [Install rbenv](https://github.com/rbenv/rbenv#installation). 1. Install the latest Ruby: ```shell - rvm install 2.6.6 + rbenv install 2.6.6 ``` 1. Use the newly installed Ruby: ```shell - rvm use 2.6.6 + rbenv global 2.6.6 ``` -Check your Ruby version with `ruby --version`. -Also check the bundled Bundler version with `bundle --version`. You will see `Bundler version 1.17.3`. +Check your: + +- Ruby version with `ruby --version`. +- Bundler version with `bundle --version`. You need version 1.17.3. ### Node The recommended way is to use a Node version manager to install Node in your system. -One way is to use NVM: +We recommend NVM: -1. [Install NVM](https://github.com/nvm-sh/nvm#installation-and-update) +1. [Install NVM](https://github.com/nvm-sh/nvm#installation-and-update). 1. Install the latest Node: ```shell - nvm install node + nvm install --lts ``` 1. Use the newly installed Node: ```shell - nvm use node + nvm use --lts --default ``` Check your Node version with `node -v`. ### Yarn -Install [yarn](https://yarnpkg.com/en/docs/install), a package manager for the Node ecosystem. +Install [yarn](https://yarnpkg.com/en/docs/install), a package manager for the +Node ecosystem. Check your Yarn version with `yarn -v`. ## Install Nanoc's dependencies -Now let's make Bundler deal with the dependencies defined in the -[`Gemfile`](/Gemfile): - -1. Open a terminal and navigate to the GitLab Docs repo -1. Switch to Ruby using RVM: - - ```shell - rvm use 2.6.6 - ``` +The project depends on many Ruby and Node libraries. To install these: +1. Open a terminal and navigate to your local checkout of this project. 1. Run: ```shell - bundle install + bundle install && yarn install --frozen-lockfile ``` ## Development when contributing to GitLab documentation This section is about contributing to one of GitLab's [projects' documentation](#projects-we-pull-from), and preview your changes at -the same time. To contribute how the docs website looks like, see +the same time. To contribute to the appearance of the documentation site, see [contributing to the docs site](#contributing-to-the-docs-website-itself). Before diving into writing, here's a few links that will come in handy: - [Writing documentation](https://docs.gitlab.com/ee/development/documentation/index.html) - [Style guide](https://docs.gitlab.com/ee/development/documentation/styleguide.html) -- [Community writers](https://about.gitlab.com/community-writers/) ### Clone the repositories Since this process will clone a few repositories, it might be a good idea to -create a separate directory to have them all together. For example, let's say -the directory will be under your user's home directory. Open a terminal and -execute: - -```shell -mkdir -p ~/dev/gitlab -``` +create a separate directory to have them all together. For example, to store all +local checkouts in a `dev` directory: -Once you do that, navigate to the directory you'd like the repos to be cloned: - -```shell -cd ~/dev/gitlab/ -``` - -Then, it's time to clone the needed repositories. - -1. First of all, clone the docs website repository: +1. Open a terminal and run: ```shell - ## Using SSH (for members that have Developer access) - git clone git@gitlab.com:gitlab-org/gitlab-docs.git - - ## Using HTTPS (for external contributors) - git clone https://gitlab.com/gitlab-org/gitlab-docs.git + mkdir -p ~/dev/ ``` -1. Then, clone the repositories you wish to contribute changes to the documentation. - For **GitLab contributors**, that do not have Developer access to the projects, - fork the ones you want (see [projects we pull from](#projects-we-pull-from)) - and then clone them by using your forked version (replace `<username>` with - your own username): +1. Navigate to the directory you'd like the repositories to be cloned: ```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 + cd ~/dev ``` - For members that have Developer access (usually the **GitLab Team members**), - clone the required repos using SSH: +1. Clone the documentation's website repository: ```shell - ## Using SSH (for members that have Developer access) + ## Using SSH (for GitLab Team members) + git clone git@gitlab.com:gitlab-org/gitlab-docs.git - git clone git@gitlab.com:gitlab-org/gitlab.git - git clone git@gitlab.com:gitlab-org/gitlab-runner.git - git clone git@gitlab.com:gitlab-org/omnibus-gitlab.git - git clone git@gitlab.com:gitlab-org/charts/gitlab.git charts + ## Using HTTPS (for external contributors) + git clone https://gitlab.com/gitlab-org/gitlab-docs.git ``` +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 git@gitlab.com:gitlab-org/gitlab.git + git clone git@gitlab.com:gitlab-org/gitlab-runner.git + git clone git@gitlab.com:gitlab-org/omnibus-gitlab.git + git clone git@gitlab.com:gitlab-org/charts/gitlab.git charts + ``` + ### Create the content symlinks Nanoc expects the Markdown files to be under `content/<slug>`, where `<slug>` -is the slug of each product as defined in [`.nanoc.yaml`](/nanoc.yaml). +is the slug of each product as defined in [`.nanoc.yaml`](nanoc.yaml). 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. -1. Open a terminal and navigate to the directory where gitlab-docs was cloned. +1. Open a terminal and navigate to the directory where `gitlab-docs` was cloned. 1. For each one of the products, create the symlink: ```shell - ln -s ~/dev/gitlab/gitlab/doc ~/dev/gitlab/gitlab-docs/content/ee - ln -s ~/dev/gitlab/omnibus-gitlab/doc ~/dev/gitlab/gitlab-docs/content/omnibus - ln -s ~/dev/gitlab/gitlab-runner/docs ~/dev/gitlab/gitlab-docs/content/runner - ln -s ~/dev/gitlab/charts/doc ~/dev/gitlab/gitlab-docs/content/charts + 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 ``` 1. Check if the symlinks were successfully created: ```shell - cd dev/gitlab/gitlab-docs + cd dev/gitlab-docs ls -la content/ ``` @@ -245,25 +212,17 @@ If they're there, we're almost good to go! directory path you are currently in and use that output to use with the symlinks commands above. -### Install node dependencies +## Preview the documentation website -1. Install node dependences in the `gitlab-docs/node_modules` folder: - - ```shell - yarn install - ``` - -## Preview the Docs website - -Run the following command to bring the embedded web server up: +Run the following command to build the documentation site and bring the embedded +web server up: ```shell -bundle exec nanoc live +bundle exec nanoc && bundle exec nanoc live ``` This will generate and the site and you will be able to view it in your browser -at <http://localhost:3000>. Any changes you make to either the website or the -content of the docs, will be reloaded automatically. +at <http://localhost:3000>. To preview the site on another port, use: @@ -282,22 +241,24 @@ of the repos: GitLab, Omnibus, Runner, or Charts), you'll need to recompile the to preview your changes: ```shell -bundle exec nanoc compile +bundle exec nanoc && bundle exec nanoc live ``` It recompiles incrementally, only updating the recently changed files. -This command can be run in parallel to `bundle exec nanoc live`, in a separate -terminal tab or window opened in `gitlab-docs`. +### Preview on mobile -Stopping `bundle exec nanoc live` with <kbd>control</kbd> + <kbd>C</kbd> and restarting -it again also works. +If you want to check how your changes look on mobile devices, you can use: -### Preview on mobile +- [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. -If you want to check how your changes look on mobile devices, you can preview -the Docs site with your own devices, as long as they are connected to the same -network as your computer. +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. 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 @@ -316,20 +277,22 @@ docs site on every device connected to your network. ### Preview on the GitLab Development Kit -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. +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. ## Contributing to the docs website itself If you want to just contribute to the docs website, and not the content, you -can use the following command to automatically pull the docs content in order +can use the following command to automatically pull the documentation content to have something to preview: ```shell bundle exec rake pull_repos ``` -This will download all the docs content under the `tmp/` directory and copy it -in `content/`. You can then [preview the website](#preview-the-docs-website). +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). If you want to force-delete the `tmp/` and `content/` folders so the task will run without manual intervention, run: @@ -372,18 +335,19 @@ we reference the array with a symbol (`:versions`). ## Modern JavaScript -Currently 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. +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. -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. +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. ### Adding a new bundle -When adding a new bundle, the layout name (html) and bundle name (js) should +When adding a new bundle, the layout name (`html`) and bundle name (`js`) should match to make it easier to find: -1. Add the new bundle to `content/frontend/<bundle-name>/<bundle-name>.js` +1. Add the new bundle to `content/frontend/<bundle-name>/<bundle-name>.js`. 1. Import the bundle in the html file `layouts/<bundle-name>.html`: ```html @@ -423,7 +387,8 @@ 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: -- Default editor: `<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>` +- Default editor: + `<a href="<%= edit_on_gitlab(@item, editor: :simple) %>">Simple editor</a>` - 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. @@ -435,11 +400,11 @@ merge request](https://docs.gitlab.com/ee/development/documentation/index.html#p ## Deployment process -We use [GitLab Pages][pages] to build and host this website, see -[`.gitlab-ci.yml`](/.gitlab-ci.yml) for more information. +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. We also use [scheduled pipelines](https://docs.gitlab.com/ee/user/project/pipelines/schedules.html) -to build the site once an hour. +to build the site once every four hours. By default, we pull from the master branch of [all the projects](#projects-we-pull-from). @@ -458,7 +423,7 @@ for its search function. This is how it works: 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 - is present on pretty much every page except https://docs.gitlab.com/search/, + is present on pretty much every page except <https://docs.gitlab.com/search/>, which uses its [own layout](/layouts/instantsearch.html). In those layouts, there's a Javascript snippet which initiates docsearch by using an API key and an index name (`gitlab`) that are needed for Algolia to show the results. @@ -469,9 +434,3 @@ 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. - -[pages]: https://about.gitlab.com/features/pages/ -[environments page]: https://gitlab.com/gitlab-org/gitlab-docs/environments/folders/review -[env-url-button]: https://docs.gitlab.com/ce/ci/environments.html#making-use-of-the-environment-url -[pipelines page]: https://gitlab.com/gitlab-org/gitlab-docs/pipelines -[new pipeline page]: https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new |