diff options
Diffstat (limited to 'doc/development/documentation/site_architecture/index.md')
| -rw-r--r-- | doc/development/documentation/site_architecture/index.md | 21 |
1 files changed, 10 insertions, 11 deletions
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 3772746e25b..be25a083948 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -1,8 +1,7 @@ --- stage: none group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers -description: "Learn how GitLab's documentation website is architectured." +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Documentation site architecture @@ -14,8 +13,8 @@ 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 +While the source of the documentation content is stored in the repositories for +each GitLab product, the source that is used to build the documentation site _from that content_ is located at <https://gitlab.com/gitlab-org/gitlab-docs>. The following diagram illustrates the relationship between the repositories @@ -46,7 +45,7 @@ from where content is sourced, the `gitlab-docs` project, and the published outp H -- symlink --> G ``` -You will not find any GitLab docs content in the `gitlab-docs` repository. +GitLab docs content isn't kept 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: @@ -55,14 +54,14 @@ product, and all together are pulled to generate the docs website: - [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) -NOTE: **Note:** +NOTE: In September 2019, we [moved towards a single codebase](https://gitlab.com/gitlab-org/gitlab/-/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. +we can remove this completely. ## Assets @@ -114,7 +113,7 @@ located in the [Dockerfiles directory](https://gitlab.com/gitlab-org/gitlab-docs If you need to rebuild the Docker images immediately (must have maintainer level permissions): -CAUTION: **Caution:** +WARNING: If you change the dockerfile configuration and rebuild the images, you can break the master pipeline in the main `gitlab` repository as well as in `gitlab-docs`. Create an image with a different name first and test it to ensure you do not break the pipelines. @@ -179,7 +178,7 @@ we reference the array with a symbol (`:versions`). Whenever the custom CSS and JavaScript files under `content/assets/` change, make sure to bump their version in the front matter. This method guarantees that -your changes will take effect by clearing the cache of previous files. +your changes 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: @@ -196,7 +195,7 @@ The links pointing to the files should be similar to: <%= @items['/path/to/assets/file.*'].path %> ``` -Nanoc will then build and render those links correctly according with what's +Nanoc then builds and renders those links correctly according with what's defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/Rules). ## Linking to source files @@ -236,7 +235,7 @@ If you’re a GitLab team member, find credentials for the Algolia dashboard in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams). 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. You'll be added to the alias that gets the weekly +and add a comment with your email to be added to the alias that gets the weekly reports. ## Monthly release process (versions) |