diff options
Diffstat (limited to 'doc/development/documentation/site_architecture')
4 files changed, 28 insertions, 27 deletions
diff --git a/doc/development/documentation/site_architecture/deployment_process.md b/doc/development/documentation/site_architecture/deployment_process.md index d92f58e5501..1b764ada87b 100644 --- a/doc/development/documentation/site_architecture/deployment_process.md +++ b/doc/development/documentation/site_architecture/deployment_process.md @@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Documentation deployment process -The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/) +The [`dockerfiles` directory](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/) contains all needed Dockerfiles to build and deploy <https://docs.gitlab.com>. It is heavily inspired by Docker's [Dockerfile](https://github.com/docker/docker.github.io/blob/06ed03db13895bfe867761b6fc2ad40acf6026dd/Dockerfile). @@ -15,10 +15,10 @@ The following Dockerfiles are used. | Dockerfile | Docker image | Description | | ---------- | ------------ | ----------- | -| [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | -| [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | -| [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch. | -| [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | +| [`Dockerfile.bootstrap`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.bootstrap) | `gitlab-docs:bootstrap` | Contains all the dependencies that are needed to build the website. If the gems are updated and `Gemfile{,.lock}` changes, the image must be rebuilt. | +| [`Dockerfile.builder.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.builder.onbuild) | `gitlab-docs:builder-onbuild` | Base image to build the docs website. It uses `ONBUILD` to perform all steps and depends on `gitlab-docs:bootstrap`. | +| [`Dockerfile.nginx.onbuild`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.nginx.onbuild) | `gitlab-docs:nginx-onbuild` | Base image to use for building documentation archives. It uses `ONBUILD` to perform all required steps to copy the archive, and relies upon its parent `Dockerfile.builder.onbuild` that is invoked when building single documentation archives (see the `Dockerfile` of each branch. | +| [`Dockerfile.archives`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/dockerfiles/Dockerfile.archives) | `gitlab-docs:archives` | Contains all the versions of the website in one archive. It copies all generated HTML files from every version in one location. | ## How to build the images @@ -36,7 +36,7 @@ and tag all tooling images locally: ``` For each image, there's a manual job under the `images` stage in -[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/.gitlab-ci.yml) which can be invoked at any time. +[`.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/.gitlab-ci.yml) which can be invoked at any time. ## Update an old Docker image with new upstream docs content @@ -55,10 +55,10 @@ The website keeps changing and being improved. In order to consolidate those changes to the stable branches, we'd need to pick certain changes from time to time. -If this is not possible or there are many changes, merge master into them: +If this is not possible or there are many changes, merge main into them: ```shell git branch 12.0 -git fetch origin master -git merge origin/master +git fetch origin main +git merge origin/main ``` diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 7175a9f1a5c..aeaf12e23d1 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -23,7 +23,7 @@ Global navigation (the left-most pane in our three pane documentation) provides: ## Adding new items To add a topic to the global nav, edit -[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/navigation.yaml) +[`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) and add your item. All new pages need a new navigation item. Without a navigation, the page becomes "orphaned". That @@ -109,7 +109,7 @@ the data among the nav in containers properly [styled](#css-classes). ### Data file The data file describes the structure of the navigation for the applicable project. -It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/master/content/_data/navigation.yaml> +It is stored at <https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml> and comprises of three main components: - Sections @@ -267,19 +267,19 @@ Examples of relative URLs: ### Layout file (logic) -The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/global_nav.html) +The [layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/global_nav.html) is fed by the [data file](#data-file), builds the global nav, and is rendered by the -[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/default.html) layout. +[default](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/default.html) layout. The global nav contains links from all [four upstream projects](index.md#architecture). The [global nav URL](#urls) has a different prefix depending on the documentation file you change. -| Repository | Link prefix | Final URL | -|----------------------------------------------------------------|-------------|-----------| -| <https://gitlab.com/gitlab-org/gitlab/tree/master/doc> | `ee/` |`https://docs.gitlab.com/ee/` | -| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` |`https://docs.gitlab.com/omnibus/` | -| <https://gitlab.com/gitlab-org/gitlab-runner/tree/master/docs> | `runner/` |`https://docs.gitlab.com/runner/` | -| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` |`https://docs.gitlab.com/charts/` | +| Repository | Link prefix | Final URL | +|----------------------------------------------------------------|-------------|------------------------------------| +| <https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc> | `ee/` | `https://docs.gitlab.com/ee/` | +| <https://gitlab.com/gitlab-org/omnibus-gitlab/tree/master/doc> | `omnibus/` | `https://docs.gitlab.com/omnibus/` | +| <https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs> | `runner/` | `https://docs.gitlab.com/runner/` | +| <https://gitlab.com/charts/gitlab/tree/master/doc> | `charts/` | `https://docs.gitlab.com/charts/` | ### CSS classes diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md index 35e9ab5157b..d410d77a1a0 100644 --- a/doc/development/documentation/site_architecture/index.md +++ b/doc/development/documentation/site_architecture/index.md @@ -49,9 +49,9 @@ 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: -- [GitLab](https://gitlab.com/gitlab-org/gitlab/tree/master/doc) +- [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 Runner](https://gitlab.com/gitlab-org/gitlab-runner/-/tree/main/docs) - [GitLab Chart](https://gitlab.com/charts/gitlab/tree/master/doc) NOTE: @@ -114,7 +114,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): WARNING: -If you change the Dockerfile configuration and rebuild the images, you can break the master +If you change the Dockerfile configuration and rebuild the images, you can break the main 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. @@ -132,7 +132,7 @@ a different name first and test it to ensure you do not break the pipelines. ### Deploy the docs site Every four hours a scheduled pipeline builds and deploys the docs site. The pipeline -fetches the current docs from the main project's master branch, builds it with Nanoc +fetches the current docs from the main project's main branch, builds it with Nanoc and deploys it to <https://docs.gitlab.com>. If you need to build and deploy the site immediately (must have maintainer level permissions): @@ -196,11 +196,11 @@ The links pointing to the files should be similar to: ``` 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). +defined in [`Rules`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/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 +A helper called [`edit_on_gitlab`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/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: @@ -223,9 +223,9 @@ for its search function. This is how it works: 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 +1. On the docs side, we use a [DocSearch layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/layouts/docsearch.html) which is present on pretty much every page except <https://docs.gitlab.com/search/>, - which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/master/layouts/instantsearch.html). In those layouts, + which uses its [own layout](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/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. diff --git a/doc/development/documentation/site_architecture/release_process.md b/doc/development/documentation/site_architecture/release_process.md index 9329b93bb26..46c74335932 100644 --- a/doc/development/documentation/site_architecture/release_process.md +++ b/doc/development/documentation/site_architecture/release_process.md @@ -1,5 +1,6 @@ --- redirect_to: 'https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases' +remove_date: '2021-07-12' --- This file was moved to [another location](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#monthly-documentation-releases). |