Docs: how the global nav works

2 files changed, 401 insertions, 0 deletions

diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md
new file mode 100644
index 00000000000..62ca7d6c805
--- /dev/null
+++ b/doc/development/documentation/site_architecture/global_nav.md
@@ -0,0 +1,342 @@
+---
+description: "Learn how GitLab docs' global navigation works and how to add new items."
+---
+
+# Global navigation
+
+> [Introduced](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/362)
+in November 2018 for GitLab 11.6.
+
+The global nav adds to the left sidebar the ability to
+navigate and explore the contents of GitLab's documentation.
+
+The global nav should be maintained consistent through time to allow the
+users to locate their most-visited links easily to facilitate navigation.
+Therefore, any updates must be carefully considered by the technical writers.
+
+## Adding new items to the global nav
+
+To add a new doc to the nav, first and foremost, check with the technical writing team:
+
+- If it's applicable
+- What's the exact position the doc will be added to the nav
+
+Once you get their approval and their guidance in regards to the position on the nav,
+read trhough this page to understand how it works, and submit a merge request to the
+docs site, adding the doc you wish to include in the nav into the
+[global nav data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml).
+
+Don't forget to ask a technical writer to review your changes before merging.
+
+## How it works
+
+The global nav has 3 components:
+
+- **Section**
+  - Category
+    - Doc
+
+The available sections are described on the table below:
+
+| Section       | Description                                |
+| ------------- | ------------------------------------------ |
+| User          | Documentation for the GitLab's user UI.    |
+| Administrator | Documentation for the GitLab's admin area. |
+| Contributor   | Documentation for developing GitLab.       |
+
+The majority of the links available on the nav were added according to the UI.
+The match is not perfect, as for some UI nav items the documentation doesn't
+apply, and there are also other links to help the new users to discover the
+documentation. The docs under **Administration** are ordered alphabetically
+for clarity.
+
+To see the improvements planned, check the
+[global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21).
+
+CAUTION: **Attention!**
+**Do not** [add items](#adding-new-items-to-the-global-nav) to the global nav without
+the consent of one of the technical writers.
+
+## Composition
+
+The global nav is built from two files:
+
+- [Data](#data-file)
+- [Layout](#layout-file)
+
+The data file feeds the layout with the links to the docs. The layout organizes
+the data among the nav in containers properly [styled](#css-classes).
+
+### Data file
+
+The [data file](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/global-nav.yaml)
+is structured in three components: sections, categories, and docs.
+
+#### Sections
+
+Each section represents the higher-level nav item. It's composed by
+title and URL:
+
+```yaml
+sections:
+  - section_title: Text
+    section_url: 'link'
+```
+
+The section can stand alone or contain categories within.
+
+#### Categories
+
+Each category within a section composes the second level of the nav.
+It includes the category title and link. It can stand alone in the nav or contain
+a third level of sub-items.
+
+Example of section with one stand-alone category:
+
+```yaml
+- section_title: Section title
+  section_url: 'section-link'
+  section_categories:
+    - category_title: Category title
+      category_url: 'category-link'
+```
+
+Example of section with two stand-alone categories:
+
+```yaml
+- section_title: Section title
+  section_url: 'section-link'
+  section_categories:
+    - category_title: Category 1 title
+      category_url: 'category-1-link'
+
+    - category_title: Category 2 title
+      category_url: 'category-2-link'
+```
+
+For clarity, **always** add a blank line between categories.
+
+If a category URL is not present in CE (it's an EE-only document), add the
+attribute `ee_only: true` below the category link. Example:
+
+```yaml
+- category_title: Category title
+  category_url: 'category-link'
+  ee_only: true
+```
+
+If the category links to an external URL, e.g., [GitLab Design System](https://design.gitlab.com),
+add the attribute `external_url: true` below the category title. Example:
+
+```yaml
+- category_title: GitLab Design System
+  category_url: 'https://design.gitlab.com'
+  external_url: true
+```
+
+#### Docs
+
+Each doc represents the third level of nav links. They must be always
+added within a category.
+
+Example with one doc link:
+
+```yaml
+- category_title: Category title
+  category_url: 'category-link'
+  docs:
+    - doc_title: Document title
+      doc_url: 'doc-link'
+```
+
+A category supports as many docs as necessary, but, for clarity, try to not
+overpopulate a category.
+
+Example with multiple docs:
+
+```yaml
+- category_title: Category title
+  category_url: 'category-link'
+  docs:
+    - doc_title: Document 1 title
+      doc_url: 'doc-1-link'
+    - doc_title: Document 2 title
+      doc_url: 'doc-2-link'
+```
+
+Whenever a document is only present in EE, add the attribute `ee-only: true`
+below the doc link. Example:
+
+```yaml
+- doc_title: Document 2 title
+  doc_url: 'doc-2-link'
+  ee_only: true
+```
+
+If you need to add a document in an external URL, add the attribute `external_url`
+below the doc link:
+
+```yaml
+- doc_title: Document 2 title
+  doc_url: 'doc-2-link'
+  external_url: true
+```
+
+All nav links are clickable. If the higher-level link does not have a link
+of its own, it must link to its first sub-item link, mimicking GitLab's navigation.
+This must be avoided so that we don't have duplicated links nor two `.active` links
+at the same time.
+
+Example:
+
+```yaml
+- category_title: Operations
+  category_url: 'user/project/integrations/prometheus_library/'
+  # until we have a link to operations, the first doc link is
+  # repeated in the category link
+  docs:
+    - doc_title: Metrics
+      doc_url: 'user/project/integrations/prometheus_library/'
+```
+
+#### Syntax
+
+For all components (sections, categories, and docs), **respect the indentation**
+and the following syntax rules.
+
+##### Titles
+
+- Use sentence case, capitalizing feature names.
+- There's no need to wrap the titles, unless there's a special char in it. E.g.,
+  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"`.
+
+##### URLs
+
+- As convention, always wrap URLs in single quotes `'url'`.
+- Always use relative paths against the home of CE and EE. Examples:
+  - For `https://docs.gitlab.com/ee/README.html`, the relative URL is `README.html`.
+  - For `https://docs.gitlab.com/ee/user/project/cycle_analytics.html`, the relative
+    URL is `user/project/cycle_analytics.html`
+- For `README.html` files, add the complete path `path/to/README.html`.
+- For `index.html` files, use the clean (canonical) URL: `path/to/`.
+- For EE-only docs, use the same relative path, but add the attribute `ee_only: true` below
+  the `doc_url` or `category_url`, as explained above. This will guarantee that when
+  the user is looking at the CE docs, it will link to the EE docs. It also displays
+  an "info" icon on the CE nav to make the user aware that it's a different link.
+
+DANGER: **Important!**
+All links present on the data file must end in `.html`, not `.md`. Do not
+start any relative link with a forward slash `/`.
+
+Examples:
+
+```yaml
+- category_title: Issues
+  category_url: 'user/project/issues/'
+  # note that the above URL does not start with a slash and 
+  # does not include index.html at the end
+
+  docs:
+    - doc_title: Service Desk
+      doc_url: 'user/project/service_desk.html'
+      ee_only: true
+      # note that the URL above ends in html and, as the
+      # document is EE-only, the attribute ee_only is set to true.
+```
+
+### Layout file (logic)
+
+The [layout](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/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-com/gitlab-docs/blob/master/layouts/default.html) layout.
+
+There are three main considerations on the logic built for the nav:
+
+- [Path](#path): first-level directories underneath `docs.gitlab.com/`:
+  - `https://docs.gitlab.com/ce/`
+  - `https://docs.gitlab.com/ee/`
+  - `https://docs.gitlab.com/omnibus/`
+  - `https://docs.gitlab.com/runner/`
+  - `https://docs.gitlab.com/debug/`
+  - `https://docs.gitlab.com/*`
+- [EE-only](#ee-only-docs): documentation only available in `/ee/`, not on `/ce/`, e.g.:
+  - `https://docs.gitlab.com/ee/user/group/epics/`
+  - `https://docs.gitlab.com/ee/user/project/security_dashboard.html`
+- [Default URL](#default-url): between CE and EE docs, the default is `ee`, therefore, all docs
+  should link to `/ee/` unless if on `/ce/` linking internally to `ce`.
+
+#### Path
+
+To use relative paths in the data file, we defined the variable `dir`
+from the root's first-child directory, which defines the path to build
+all the nav links to other pages:
+
+```html
+<% dir = @item.identifier.to_s[%r{(?<=/)[^/]+}] %>
+```
+
+For instance, for `https://docs.gitlab.com/ce/user/index.html`,
+`dir` == `ce`, and for `https://docs.gitlab.com/omnibus/README.html`,
+`dir` == `omnibus`.
+
+#### Default URL
+
+The default and canonical URL for GitLab documentation is
+`http://docs.gitlab.com/ee/`, thus, all links
+in the docs site should link to `/ee/` except when linking
+among `/ce/` docs themselves.
+
+Therefore, if the user is looking at `/ee/`, `/omnibus/`,
+`/runner/`, or any other highest-level dir, the nav should
+point to `/ee/` docs.
+
+On the other hand, if the user is looking at `/ce/` docs,
+all the links in the CE nav should link internally to `/ce/`
+files, except for [`ee-only` docs](#ee-only-docs).
+
+
+```html
+<% if dir != 'ce' %>
+  <a href="/ee/<%= sec[:section_url] %>">...</a>
+  <% else %>
+    <a href="/<%= dir %>/<%= sec[:section_url] %>">...</a>
+  <% end %>
+  ...
+<% end %>
+```
+
+This also allows the nav to be displayed on other
+highest-level dirs (`/omnibus/`, `/runner/`, etc),
+linking them back to `/ee/`.
+
+The same logic is applied to all sections (`sec[:section_url]`),
+categories (`cat[:category_url]`), and docs (`doc[:doc_url]`) URLs.
+
+#### `ee-only` docs
+
+If the user is looking at the CE nav, a given doc is present only
+in `/ee/`, it's tagged in the data file by `ee-only`, linking it
+directly to `/ee/`.
+
+```html
+<% if dir == 'ce' && cat[:ee_only] %>
+   <a href="/ee/<%= cat[:category_url] %>">...</a>
+<% end %>
+```
+
+To make it clear that it it's a different link, an icon is displayed
+on the nav link indicating that the `ee-only` doc is not available in CE.
+
+The `ee-only` attribute is available for `categories` (`<% if dir == 'ce' && cat[:ee_only] %>`)
+and `docs` (`<% if dir == 'ce' && doc[:ee_only] %>`), but not for `sections`.
+
+### CSS classes
+
+The nav is styled in the general `stylesheet.scss`. 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.
diff --git a/doc/development/documentation/site_architecture/index.md b/doc/development/documentation/site_architecture/index.md
new file mode 100644
index 00000000000..956bf90a5d9
--- /dev/null
+++ b/doc/development/documentation/site_architecture/index.md
@@ -0,0 +1,59 @@
+---
+description: "Learn how GitLab's documentation website is architectured."
+---
+
+# Docs site architecture
+
+Learn how we build and architecture [`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs)
+and deploy it to <https://docs.gitlab.com>.
+
+## 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 3.3 components](https://getbootstrap.com/docs/3.3/components/)
+- [Bootstrap 3.3 JS](https://getbootstrap.com/docs/3.3/javascript/)
+- [jQuery](https://jquery.com/) 3.2.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 nav
+
+To understand how the global nav (left sidebar) is built, please
+read through the [global navigation](global_nav.md) doc.
+
+## Deployment
+
+The docs site is deployed to production with GitLab Pages, and previewed in
+merge requests with Review Apps.
+
+The deployment aspects will be soon transfered from the [original document](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md)
+to this page.
+
+<!--
+## Repositories
+
+TBA
+
+## Search engine
+
+TBA
+
+## Versions
+
+TBA
+
+## Helpers
+
+TBA
+-->