From 368bd3cd692ee1186d52a7777521c4028898fa16 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Wed, 3 Sep 2025 16:59:05 +0900 Subject: [PATCH 1/2] Update hugo shortcode details We simplified the shortcodes when we rolled them out, but the guidance was not update due to being in code blocks. --- doc/.vale/gitlab_docs/HistoryItems.yml | 2 +- .../documentation/experiment_beta.md | 12 ++-- .../documentation/feature_flags.md | 44 ++++++------ .../documentation/graphql_styleguide.md | 4 +- .../documentation/restful_api_styleguide.md | 18 ++--- .../documentation/styleguide/_index.md | 72 +++++++++---------- .../styleguide/availability_details.md | 20 +++--- .../styleguide/deprecations_and_removals.md | 28 ++++---- .../topic_types/top_level_page.md | 4 +- .../topic_types/troubleshooting.md | 4 +- .../topic_types/version_specific_changes.md | 4 +- 11 files changed, 106 insertions(+), 106 deletions(-) diff --git a/doc/.vale/gitlab_docs/HistoryItems.yml b/doc/.vale/gitlab_docs/HistoryItems.yml index c3f7d2cace74f2..2c454d4e64c758 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 3ecc10423877df..21fd166865f11b 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 e69cc92d3d61c7..dc98a717184b92 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 7a7c03c18593ad..12bdd8d4301815 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 51180191a92fb1..aa3c37c428592a 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 3ef90abbe6c542..5bd81fc13c733f 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 3ba9da665d6269..6f16a9a77a706c 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 7a1e5576ca8703..8330ed585909fc 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 8054f9ff1a3e6f..7e64f8ea1051de 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 442d8b33f5ca78..2538cb54240c61 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 39d8ea3aac018a..01af02ac268948 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: -- GitLab From a2cef0428bf9bd8c10b95af7860bf6542e663249 Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Wed, 3 Sep 2025 17:50:02 +0900 Subject: [PATCH 2/2] Add closing slashes to short code examples --- doc/development/documentation/feature_flags.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index dc98a717184b92..9a91bf7116f373 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -153,7 +153,7 @@ When the flag is removed, add a `Generally available` entry. Ensure that you del - [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 >}} +{{< /history >}} ``` ## Simplify long history @@ -207,5 +207,5 @@ Delete `Enabled on GitLab.com` entries only when the feature is enabled by defau - [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 >}} + {{< /history >}} ``` -- GitLab