--- description: "Learn how GitLab's documentation website is architectured." --- # Documentation site architecture The [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) project hosts the repository which is used to generate the GitLab documentation website and is deployed to . It uses the [Nanoc](http://nanoc.ws) static site generator. ## Architecture While the source of the documentation content is stored in GitLab's respective product repositories, the source that is used to build the documentation site _from that content_ is located at . The following diagram illustrates the relationship between the repositories from where content is sourced, the `gitlab-docs` project, and the published output. ```mermaid graph LR A[gitlab-foss/doc] B[gitlab/doc] C[gitlab-runner/docs] D[omnibus-gitlab/doc] E[charts/doc] F[gitlab-docs] A --> F B --> F C --> F D --> F E --> F F -- Build pipeline --> G G[docs.gitlab.com] H[/ce/] I[/ee/] J[/runner/] K[/omnibus/] L[/charts/] G --> H G --> I G --> J G --> K G --> L ``` You will not find any GitLab docs content in the `gitlab-docs` repository. All documentation files are hosted in the respective repository of each product, and all together are pulled to generate the docs website: - [GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) - [Omnibus GitLab](https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc) - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) NOTE: **Note:** In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab-ee/issues/2952), as such the docs for CE and EE are now identical. For historical reasons and in order not to break any existing links throughout the internet, we still maintain the CE docs (`https://docs.gitlab.com/ce/`), although it is hidden from the website, and is now a symlink to the EE docs. When [Pages supports redirects](https://gitlab.com/gitlab-org/gitlab-pages/issues/24), we will be able to remove this completely. ## Assets To provide an optimized site structure, design, and a search-engine friendly website, along with a discoverable documentation, we use a few assets for the GitLab Documentation website. ### Libraries - [Bootstrap 4.3.1 components](https://getbootstrap.com/docs/4.3/components/) - [Bootstrap 4.3.1 JS](https://getbootstrap.com/docs/4.3/getting-started/javascript/) - [jQuery](https://jquery.com/) 3.3.1 - [Clipboard JS](https://clipboardjs.com/) - [Font Awesome 4.7.0](https://fontawesome.com/v4.7.0/icons/) ### SEO - [Schema.org](https://schema.org/) - [Google Analytics](https://marketingplatform.google.com/about/analytics/) - [Google Tag Manager](https://developers.google.com/tag-manager/) ## Global navigation Read through [the global navigation documentation](global_nav.md) to understand: - How the global navigation is built. - How to add new navigation items. ## 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 | %>

<%= version %>

<% end &> ``` Note that the data file must have the `yaml` extension (not `yml`) and that we reference the array with a symbol (`:versions`). ## Bumping versions of CSS and JavaScript Whenever the custom CSS and JavaScript files under `content/assets/` change, 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. Always use Nanoc's way of including those files, do not hardcode them in the layouts. For example use: ```erb ``` 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`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules). ## Linking to source files A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/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: `Simple editor` - Web IDE: `Web IDE` If you don't specify `editor:`, the simple one is used by default. ## Algolia search engine 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](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/docsearch.html) which is present on pretty much every page except , which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/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. NOTE: **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. ## Monthly release process (versions) The docs website supports versions and each month we add the latest one to the list. For more information, read about the [monthly release process](release_process.md). ## Review Apps for documentation merge requests If you are contributing to GitLab docs read how to [create a Review App with each merge request](../index.md#previewing-the-changes-live).