diff --git a/doc/.vale/gitlab_docs/HistoryItems.yml b/doc/.vale/gitlab_docs/HistoryItems.yml index c3f7d2cace74f2f124fffc4e8e691e326396e680..2c454d4e64c758009af3c9bec473b50df94870e3 100644 --- a/doc/.vale/gitlab_docs/HistoryItems.yml +++ b/doc/.vale/gitlab_docs/HistoryItems.yml @@ -10,6 +10,6 @@ level: error nonword: true scope: raw tokens: - - '\{\{< history >\}\}\n\n[^-]' + - '(?\}\}\n\n[^-]' - '(^#+[^\n]*|\{\{< /details >\}\})\n\n>' - '^##.*?\n\n- \[?(Introduced|Changed|Renamed|Updated|Improved|Generally)' diff --git a/doc/development/documentation/experiment_beta.md b/doc/development/documentation/experiment_beta.md index 3ecc10423877dfeec08ef652febc19db593e9161..21fd166865f11b10721147346cfef66b0c1e0464 100644 --- a/doc/development/documentation/experiment_beta.md +++ b/doc/development/documentation/experiment_beta.md @@ -29,25 +29,25 @@ For example: ```markdown ## Great new feature -{{}} +{{< details >}} Status: Experiment -{{}} +{{< /details >}} -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab 15.10. This feature is an [experiment](/policy/development_stages_support.md). -{{}} +{{< /history >}} -{{}} +{{< alert type="flag" >}} The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use. -{{}} +{{< /alert >}} Use this new feature when you need to do this new thing. diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index e69cc92d3d61c79c73df386317e24da76849c166..9a91bf7116f3732bda9ebe9823b7700677e59b08 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -47,7 +47,7 @@ When the state of a flag changes (for example, from disabled by default to enabl Possible history entries are: ```markdown -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab X.X [with a flag](../../administration/feature_flags/_index.md) named `flag_name`. Disabled by default. - [Enabled on GitLab.com](https://issue-link) in GitLab X.X. @@ -55,7 +55,7 @@ Possible history entries are: - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://issue-link) in GitLab X.X. - [Generally available](https://issue-link) in GitLab X.Y. Feature flag `flag_name` removed. -{{}} +{{< /history >}} ``` These entries might not fit every scenario. You can adjust to suit your needs. @@ -71,13 +71,13 @@ Add this feature flag note at the start of the topic, just below the history. The final sentence (`not ready for production use`) is optional. ```markdown -{{}} +{{< alert type="flag" >}} The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use. -{{}} +{{< /alert >}} ``` This note renders on the GitLab documentation site as: @@ -95,65 +95,65 @@ This feature is available for testing, but not ready for production use. The following examples show the progression of a feature flag. Update the history with every change: ```markdown -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags/_index.md) named `forti_token_cloud`. Disabled by default. -{{}} +{{< /history >}} -{{}} +{{< alert type="flag" >}} The availability of this feature is controlled by a feature flag. For more information, see the history. -{{}} +{{< /alert >}} ``` When the feature is enabled by default on GitLab.com: ```markdown -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags/_index.md) named `forti_token_cloud`. Disabled by default. - [Enabled on GitLab.com](https://issue-link) in GitLab 13.8. -{{}} +{{< /history >}} -{{}} +{{< alert type="flag" >}} The availability of this feature is controlled by a feature flag. For more information, see the history. -{{}} +{{< /alert >}} ``` When the feature is enabled by default for all offerings: ```markdown -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags/_index.md) named `forti_token_cloud`. Disabled by default. - [Enabled on GitLab.com](https://issue-link) in GitLab 13.8. - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 13.9. -{{}} +{{< /history >}} -{{}} +{{< alert type="flag" >}} The availability of this feature is controlled by a feature flag. For more information, see the history. -{{}} +{{< /alert >}} ``` When the flag is removed, add a `Generally available` entry. Ensure that you delete the `FLAG` note as well: ```markdown -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags/_index.md) named `forti_token_cloud`. Disabled by default. - [Enabled on GitLab.com](https://issue-link) in GitLab 13.8. - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 13.9. - [Generally available](https://issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. -{{}} +{{< /history >}} ``` ## Simplify long history @@ -188,24 +188,24 @@ Delete `Enabled on GitLab.com` entries only when the feature is enabled by defau - Before: ```markdown - {{}} + {{< history >}} - [Introduced](https://issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags/_index.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. - [Enabled on GitLab.com](https://issue-link) in GitLab 15.7. - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 15.8. - [Generally available](https://issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed. - {{}} + {{< /history >}} ``` - After: ```markdown - {{}} + {{< history >}} - [Introduced](https://issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags/_index.md) named `ci_hooks_pre_get_sources_script`. Disabled by default. - [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 15.8. - [Generally available](https://issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed. - {{}} + {{< /history >}} ``` diff --git a/doc/development/documentation/graphql_styleguide.md b/doc/development/documentation/graphql_styleguide.md index 7a7c03c18593adde3dc3b02f29819e43ef235d60..12bdd8d43018154123200ad589edc6add26f195d 100644 --- a/doc/development/documentation/graphql_styleguide.md +++ b/doc/development/documentation/graphql_styleguide.md @@ -38,12 +38,12 @@ info: To determine the technical writer assigned to the Stage/Group associated w title: List branch rules for a project by using GraphQL --- -{{}} +{{< details >}} - Tier: Free, Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated -{{}} +{{< /details >}} ``` For help editing this content for your use case, ask a technical writer. diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 51180191a92fb1cf4f419694338451dd21c1a3cb..aa3c37c428592aece6f759f790494716d4f8a18a 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -45,21 +45,21 @@ required attributes first in the table. ````markdown ## API name -{{}} +{{< history >}} - History note. -{{}} +{{< /history >}} One or two sentence description of what endpoint does. ### Method title -{{}} +{{< history >}} - History note. -{{}} +{{< /history >}} Description of the method. @@ -112,11 +112,11 @@ for the section. For example: ```markdown ### Edit a widget -{{}} +{{< history >}} - - `widget_message` [introduced](https://link-to-issue) in GitLab 14.3. +- `widget_message` [introduced](https://link-to-issue) in GitLab 14.3. -{{}} +{{< /history >}} ``` If the API or attribute is deployed behind a feature flag, @@ -132,11 +132,11 @@ To deprecate an attribute: 1. Add a history note. ```markdown - {{}} + {{< history >}} - `widget_name` [deprecated](https://link-to-issue) in GitLab 14.7. - {{}} + {{< /history >}} ``` 1. Add inline deprecation text to the description. diff --git a/doc/development/documentation/styleguide/_index.md b/doc/development/documentation/styleguide/_index.md index 3ef90abbe6c542242a384c4d8175b41c2f8d173a..5bd81fc13c733f783d4c081c6982e6ac983aaad6 100644 --- a/doc/development/documentation/styleguide/_index.md +++ b/doc/development/documentation/styleguide/_index.md @@ -837,8 +837,8 @@ page), use these phrases: | Option | Markdown | Displayed result | |--------|---------------------------------------------------|------------------| -| No | `{{}} No` | {{< icon name="dash-circle" >}} No | -| Yes | `{{}} Yes` | {{< icon name="check-circle-filled" >}} Yes | +| No | `{{< icon name="dash-circle" >}} No` | {{< icon name="dash-circle" >}} No | +| Yes | `{{< icon name="check-circle-filled" >}} Yes` | {{< icon name="check-circle-filled" >}} Yes | Do not use these SVG icons in API documentation. Instead, follow the [API topic template](../restful_api_styleguide.md#api-topic-template). @@ -1678,7 +1678,7 @@ Don't use the Markdown emoji format, for example `:smile:`, for any purpose. Use ## GitLab SVG icons You can use icons from the [GitLab SVG library](https://gitlab-org.gitlab.io/gitlab-svgs/) -directly in the documentation. For example, `{{}}` renders as: {{< icon name="tanuki" >}}. +directly in the documentation. For example, `{{< icon name="tanuki" >}}` renders as: {{< icon name="tanuki" >}}. In most cases, avoid icons in text. However, use the icon when hover text is the only @@ -1687,21 +1687,21 @@ often have hover text only. When you do use an icon, start with the hover text and follow it with the SVG reference in parentheses. -- Avoid: `Select {{}} **Edit**.` This generates as: Select {{< icon name="pencil" >}} **Edit**. -- Use instead: `Select **Edit** ({{}}).` This generates as: Select **Edit** ({{< icon name="pencil" >}}). +- Avoid: `Select {{< icon name="pencil" >}} **Edit**.` This generates as: Select {{< icon name="pencil" >}} **Edit**. +- Use instead: `Select **Edit** ({{< icon name="pencil" >}}).` This generates as: Select **Edit** ({{< icon name="pencil" >}}). Do not use words to describe the icon: - Avoid: `Select **Erase job log** (the trash icon).` -- Use instead: `Select **Erase job log** ({{}}).` This generates as: Select **Erase job log** ({{< icon name="remove" >}}). +- Use instead: `Select **Erase job log** ({{< icon name="remove" >}}).` This generates as: Select **Erase job log** ({{< icon name="remove" >}}). When the button doesn't have any hover text, describe the icon. Follow up by creating a [UX bug issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Bug) to add hover text to the button to improve accessibility. -- Avoid: `Select {{}}.` -- Use instead: `Select the vertical ellipsis ({{}}).` This generates as: Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}). +- Avoid: `Select {{< icon name="ellipsis_v" >}}.` +- Use instead: `Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}).` This generates as: Select the vertical ellipsis ({{< icon name="ellipsis_v" >}}). ## Videos @@ -1805,11 +1805,11 @@ Use alert boxes to call attention to information. Use them sparingly, and never Alert boxes are generated by using a Hugo shortcode: ```plaintext -{{}} +{{< alert type="note" >}} This is something to note. -{{}} +{{< /alert >}} ``` The valid alert types are `flag`, `note`, `warning`, and `disclaimer`. @@ -1835,11 +1835,11 @@ Instead of adding a note: If you must use a note, use this format: ```markdown -{{}} +{{< alert type="note" >}} This is something to note. -{{}} +{{< /alert >}} ``` It renders on the GitLab documentation site as: @@ -1856,11 +1856,11 @@ Use a warning to indicate deprecated features, or to provide a warning about procedures that have the potential for data loss. ```markdown -{{}} +{{< alert type="warning" >}} This is something to be warned about. -{{}} +{{< /alert >}} ``` It renders on the GitLab documentation site as: @@ -1881,7 +1881,7 @@ any other text. Add a disclaimer like this: ```plaintext -{{}} +{{< alert type="disclaimer" />}} ``` It renders on the GitLab documentation site as: @@ -1920,21 +1920,21 @@ Do not put version history bullets, topic headings, HTML, or tabs in tabs. Only To create a set of tabs, follow this example: ```plaintext -{{}} +{{< tabs >}} -{{}} +{{< tab title="Tab one" >}} Here's some content in tab one. -{{}} +{{< /tab >}} -{{}} +{{< tab title="Tab two" >}} Here's some other content in tab two. -{{}} +{{< /tab >}} -{{}} +{{< /tabs >}} ``` This code renders on the GitLab documentation site as: @@ -1975,24 +1975,24 @@ Use cards to create landing pages with links to sub-pages. To create a set of cards, follow this example: ```markdown -{{}} +{{< cards >}} - [The first page](first_page.md) - [Another page](another/page.md) - [One more page](one_more.md) -{{}} +{{< /cards >}} ``` Additionally, cards support external URLs with optional descriptions. Use the following syntax: ```markdown -{{}} +{{< cards >}} - [External page title](https://example.com "Optional Description") -{{}} +{{< /cards >}} ``` Cards render only on the GitLab documentation site (`https://docs.gitlab.com`). @@ -2009,7 +2009,7 @@ maintained GitLab versions as specified by the [maintenance policy](../../../policy/maintenance.md): ```markdown -{{}} +{{< maintained-versions >}} ``` Maintained versions render only on the pre-release version of the GitLab @@ -2125,9 +2125,9 @@ GitLab, or restart GitLab. In this case: When describing a configuration edit, use this snippet, editing it as needed: ````markdown -{{}} +{{< tabs >}} -{{}} +{{< tab title="Linux package (Omnibus)" >}} 1. Edit `/etc/gitlab/gitlab.rb`: @@ -2141,9 +2141,9 @@ When describing a configuration edit, use this snippet, editing it as needed: sudo gitlab-ctl reconfigure ``` -{{}} +{{< /tab >}} -{{}} +{{< tab title="Helm chart (Kubernetes)" >}} 1. Export the Helm values: @@ -2166,9 +2166,9 @@ When describing a configuration edit, use this snippet, editing it as needed: helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab ``` -{{}} +{{< /tab >}} -{{}} +{{< tab title="Docker" >}} 1. Edit `docker-compose.yml`: @@ -2187,9 +2187,9 @@ When describing a configuration edit, use this snippet, editing it as needed: docker compose up -d ``` -{{}} +{{< /tab >}} -{{}} +{{< tab title="Self-compiled (source)" >}} 1. Edit `/home/git/gitlab/config/gitlab.yml`: @@ -2209,9 +2209,9 @@ When describing a configuration edit, use this snippet, editing it as needed: sudo service gitlab restart ``` -{{}} +{{< /tab >}} -{{}} +{{< /tabs >}} ```` It renders as: diff --git a/doc/development/documentation/styleguide/availability_details.md b/doc/development/documentation/styleguide/availability_details.md index 3ba9da665d62691bea951e0de1f3e31f2dbed9f7..6f16a9a77a706c2c4772be213d3002dca8480841 100644 --- a/doc/development/documentation/styleguide/availability_details.md +++ b/doc/development/documentation/styleguide/availability_details.md @@ -21,21 +21,21 @@ The Markdown for availability details should look like the following: title: 'Topic title' --- -{{}} +{{< details >}} - Tier: Free, Premium, Ultimate - Add-on: GitLab Duo Enterprise - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated - Status: Experiment -{{}} +{{< /details >}} -{{}} +{{< history >}} - [Introduced](https://link-to-issue) in GitLab 16.3. - Updated in GitLab 16.4. -{{}} +{{< /history >}} ``` ## Available options @@ -131,12 +131,12 @@ The documentation site uses [shortcodes](../hugo_migration.md#shortcodes) to ren for example: ```markdown -{{}} +{{< history >}} - [Introduced](https://issue-link) in GitLab 16.3. - [Changed](https://issue-link) in GitLab 16.4. -{{}} +{{< /history >}} ``` In addition: @@ -291,12 +291,12 @@ don't need to duplicate the details if the page details match: title: My title --- -{{}} +{{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com -{{}} +{{< /details >}} ``` Any lower-level heading that applies to a different tier but same offering would be: @@ -304,11 +304,11 @@ Any lower-level heading that applies to a different tier but same offering would ```markdown ## My title -{{}} +{{< details >}} - Tier: Ultimate -{{}} +{{< /details >}} ``` ## Inline availability details diff --git a/doc/development/documentation/styleguide/deprecations_and_removals.md b/doc/development/documentation/styleguide/deprecations_and_removals.md index 7a1e5576ca87038d1f6062d8bb780f30c48095ef..8330ed585909fc0a911503f1e309293cd609f56d 100644 --- a/doc/development/documentation/styleguide/deprecations_and_removals.md +++ b/doc/development/documentation/styleguide/deprecations_and_removals.md @@ -27,12 +27,12 @@ When a feature is no longer actively developed, but not deprecated, add the foll the topic title and version history: ```markdown -{{}} +{{< alert type="note" >}} This feature is not under active development, but [community contributions](https://about.gitlab.com/community/contribute/) are welcome. -{{}} +{{< /alert >}} ``` ## Deprecate a page or topic @@ -46,19 +46,19 @@ To deprecate a page or topic: title: Title (deprecated) --- - {{}} + {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated - {{}} + {{< /details >}} - {{}} + {{< alert type="warning" >}} This feature was [deprecated](https://issue-link) in GitLab 14.8 and is planned for removal in 15.4. Use [feature X](link-to-docs.md) instead. - {{}} + {{< /alert >}} ``` If you're not sure when the feature will be removed or no @@ -81,19 +81,19 @@ To deprecate a page or topic: - {{}} + {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated - {{}} + {{< /details >}} - {{}} + {{< alert type="warning" >}} This feature was [deprecated](https://issue-link) in GitLab 14.8 and is planned for removal in 15.4. Use [feature X](link-to-docs.md) instead. - {{}} + {{< /alert >}} ``` @@ -125,12 +125,12 @@ To remove a page: title: Title (removed) --- - {{}} + {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated - {{}} + {{< /details >}} This feature was [deprecated](https://issue-link) in GitLab X.Y and [removed](https://issue-link) in X.Y. @@ -170,12 +170,12 @@ To remove a topic: - {{}} + {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated - {{}} + {{< /details >}} This feature was [deprecated](https://issue-link) in GitLab X.Y and [removed](https://issue-link) in X.Y. diff --git a/doc/development/documentation/topic_types/top_level_page.md b/doc/development/documentation/topic_types/top_level_page.md index 8054f9ff1a3e6fc9ee38ebf955cc0689fd28b8f7..7e64f8ea1051dea87f90400698782e3fdf9bb7d9 100644 --- a/doc/development/documentation/topic_types/top_level_page.md +++ b/doc/development/documentation/topic_types/top_level_page.md @@ -21,13 +21,13 @@ title: Title (The name of the top-level page, like "Manage your organization") List features in the workflow, in the order they appear in the global navigation. -{{}} +{{< cards >}} - [The first page](first_page.md) - [Another page](another/page.md) - [One more page](one_more.md) -{{}} +{{< /cards >}} ``` ## Top-level page titles diff --git a/doc/development/documentation/topic_types/troubleshooting.md b/doc/development/documentation/topic_types/troubleshooting.md index 442d8b33f5ca787b8a42d2baa292f8462ffbeebb..2538cb54240c61edec3b924af8ff819d3604ed2c 100644 --- a/doc/development/documentation/topic_types/troubleshooting.md +++ b/doc/development/documentation/topic_types/troubleshooting.md @@ -93,11 +93,11 @@ If the troubleshooting suggestion includes a function that changes data on the G add the following warning: ```markdown -{{}} +{{< alert type="warning" >}} Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore. -{{}} +{{< /alert >}} ``` ## Troubleshooting page type diff --git a/doc/development/documentation/topic_types/version_specific_changes.md b/doc/development/documentation/topic_types/version_specific_changes.md index 39d8ea3aac018a709aca98fe613fde4c57cc36d8..01af02ac2689486635ee30eed0ff6a4688d318c4 100644 --- a/doc/development/documentation/topic_types/version_specific_changes.md +++ b/doc/development/documentation/topic_types/version_specific_changes.md @@ -25,12 +25,12 @@ The version-specific upgrade notes page should use the following format: title: GitLab X upgrade notes --- -{{}} +{{< details >}} - Tier: Free, Premium, Ultimate - Offering: GitLab Self-Managed -{{}} +{{< /details >}} This page contains upgrade information for minor and patch versions of GitLab X. Ensure you review these instructions for: