diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 05a0c9062c65994e66b5638feabf6f1eedf59e64..bdeb7af8ee15ec8cc0c80e63288bd965a7a5e0b8 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -80,8 +80,8 @@ left side of the documentation website). To do so, open a second MR, against the [GitLab documentation repository](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/). The global navigation is set in the -[`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml) file, -in the `content/data` subdirectory. You can find the GraphQL section under the +[`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml) file, +in the `content/data/en-us` subdirectory. You can find the GraphQL section under the following line: ```yaml diff --git a/doc/development/documentation/metadata.md b/doc/development/documentation/metadata.md index 8ce3e59ed4ed5412fb454063cbc790820bf05aeb..c3836d62187c5c65654a7ccabb3d45fe1b92848d 100644 --- a/doc/development/documentation/metadata.md +++ b/doc/development/documentation/metadata.md @@ -84,7 +84,7 @@ See the Google [Best practices for creating quality meta descriptions](https://d ## Avoid pages being added to global navigation If a specific page shouldn't be added to the global navigation (have an entry added to -[`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml), add +[`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml), add the following to the page's metadata: ```yaml diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 4eef94b0f470d204a36b252f4ede2641d5ca5e69..057353167d04aa43a863151abb500bbaf41c3898 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -36,7 +36,7 @@ In the Markdown doc for a resource (AKA endpoint): description also has both offering and tier, combine them. For example: _GitLab Self-Managed, Premium and Ultimate only._ -After a new API documentation page is added, [add an entry in the global navigation](site_architecture/global_nav.md#add-a-navigation-entry). [Examples](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/commits/main/data/navigation.yaml). +After a new API documentation page is added, [add an entry in the global navigation](site_architecture/global_nav.md#add-a-navigation-entry). [Examples](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/commits/main/data/en-us/navigation.yaml). ## API topic template diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 66c552140cde430cd2c668452c4034db30d470bd..7601553ec08bd27db75305772b8ccaf0c3855a3f 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -40,7 +40,7 @@ as helpful as **Get started with runners**. ## Add a navigation entry The global nav is stored in the `gitlab-org/technical-writing/docs-gitlab-com` project, in the -`data/navigation.yaml` file. The documentation website at `docs.gitlab.com` is built using Hugo and assembles documentation +`data/en-us/navigation.yaml` file. The documentation website at `docs.gitlab.com` is built using Hugo and assembles documentation content from several projects (including `charts`, `gitlab`, `gitlab-runner`, and `omnibus-gitlab`). **Do not** add items to the global nav without @@ -48,7 +48,7 @@ the consent of one of the technical writers. To add a topic to the global navigation: -1. In the [`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml) +1. In the [`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml) file, add the item. 1. Assign the MR to a technical writer for review and merge. @@ -90,7 +90,6 @@ mechanics of what is required is [documented below](#data-file) but, in principl Exclude these pages from the global nav: - Legal notices. -- Pages in the `architecture/blueprints` directory. - Pages in the `user/application_security/dast/checks/` directory. The following pages should probably be in the global nav, but the technical writers @@ -106,18 +105,6 @@ All other pages should be in the global nav. The technical writing team runs a report to determine which pages are not in the nav. The team reviews this list each month. -## Navigation structure - -The global nav has five levels: - -- Section - - Category - - Doc - - Doc - - Doc - -You can view this structure in the [`navigation.yml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml?ref_type=heads) file. - ### Use GitLab section In addition to feature documentation, each category in the **Use GitLab** section should contain: @@ -148,7 +135,7 @@ The layout organizes the data among the nav in containers properly [styled](#css ### Data file The data file describes the structure of the navigation for the applicable project. -It is stored at <https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml>. +It is stored at <https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml>. Each entry comprises of three main components: @@ -187,7 +174,7 @@ For all components, **respect the indentation** and the following syntax rules. - Use sentence case, capitalizing feature names. - There's no need to wrap the titles, unless there's a special character in it. For example, in `GitLab CI/CD`, there's a `/` present, therefore, it must be wrapped in quotes. - As convention, wrap the titles in double quotes: `category_title: "GitLab CI/CD"`. + As convention, wrap the titles in double quotes: `title: "GitLab CI/CD"`. ##### URLs @@ -198,8 +185,7 @@ URLs must be relative. In addition: - Match the path you see on the website. - As convention, always wrap URLs in single quotes `'url'`. To find the global nav link, from the full URL remove `https://docs.gitlab.com/`. -- Do not link to external URLs. We don't have link checking for external URLs, and - leaving the documentation site by clicking the left navigation is a confusing user experience. +- Do not link to external URLs. Leaving the documentation site by clicking the left navigation is a confusing user experience. Examples of relative URLs: @@ -230,14 +216,9 @@ The [global nav URL](#urls) has a different prefix depending on the documentatio ### CSS classes -The nav is styled in the general `stylesheet.scss`. To change +The nav is styled in the general `main.css` file. To change its styles, keep them grouped for better development among the team. -The URL components have their unique styles set by the CSS classes `.level-0`, -`.level-1`, and `.level-2`. To adjust the link's font size, padding, color, etc, -use these classes. This way we guarantee that the rules for each link do not conflict - with other rules in the stylesheets. - ## Testing We run various checks on `navigation.yaml` in [`check-navigation.sh`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/main/scripts/check-navigation.sh), diff --git a/doc/development/documentation/styleguide/deprecations_and_removals.md b/doc/development/documentation/styleguide/deprecations_and_removals.md index c089f90f52d2ef757c1dda4a679294344d205ccf..09db42828893a1341644e12cc95ace5ea91ca10f 100644 --- a/doc/development/documentation/styleguide/deprecations_and_removals.md +++ b/doc/development/documentation/styleguide/deprecations_and_removals.md @@ -135,7 +135,7 @@ To remove a page: Use [feature X](link-to-docs.md) instead. ``` -1. Edit the [`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml) in `docs-gitlab-com` +1. Edit the [`navigation.yaml`](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml) in `docs-gitlab-com` to remove the page's entry from the global navigation. 1. Search the [Deprecations and Removals](../../../update/deprecations.md) page for links to the removed page. The links use full URLs like: `https://docs.gitlab.com/user/deprecated_page/`. diff --git a/doc/development/integrations/_index.md b/doc/development/integrations/_index.md index ad293424d31def910d2b2f5352da674df8220c9c..63e1bb9251f2102e0ab1c81f007eb1505d084f3b 100644 --- a/doc/development/integrations/_index.md +++ b/doc/development/integrations/_index.md @@ -460,7 +460,7 @@ Add documentation for the integration: - Add a page in `doc/user/project/integrations`. - Link it from the [Integrations overview](../../user/project/integrations/_index.md). - After the documentation has merged, [add an entry](../documentation/site_architecture/global_nav.md#add-a-navigation-entry) - to the documentation navigation under [Integrations](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/navigation.yaml?ref_type=heads#L2936). + to the documentation navigation under [Integrations](https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml?ref_type=heads#L2936). You can also refer to our general [documentation guidelines](../documentation/_index.md).