Commit f415012c authored by Marcin Sedlak-Jakubowski's avatar Marcin Sedlak-Jakubowski Committed by Marcia Ramos

Fix footnote examples in Markdown docs

parent 8f917e2a
...@@ -100,12 +100,15 @@ The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its ...@@ -100,12 +100,15 @@ The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. That is, Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. That is,
all markup that is supported for display in the GitLab application itself. For now, all markup supported for display in the GitLab application itself. For now,
use regular Markdown markup, following the rules in the linked style guide. use regular Markdown markup, following the rules in the linked style guide.
Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help). Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help).
Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as: ### HTML in Markdown
Hard-coded HTML is valid, although it's discouraged from being used while we have `/help`.
HTML is permitted as long as:
- There's no equivalent markup in Markdown. - There's no equivalent markup in Markdown.
- Advanced tables are necessary. - Advanced tables are necessary.
...@@ -130,7 +133,7 @@ to verify that proper capitalization and backticks are used. Words in backticks ...@@ -130,7 +133,7 @@ to verify that proper capitalization and backticks are used. Words in backticks
be ignored by markdownlint. be ignored by markdownlint.
In general, product names should follow the exact capitalization of the official names In general, product names should follow the exact capitalization of the official names
of the products, protocols, etc. of the products, protocols, and so on.
Some examples that will fail if incorrect capitalization is used: Some examples that will fail if incorrect capitalization is used:
...@@ -138,7 +141,7 @@ Some examples that will fail if incorrect capitalization is used: ...@@ -138,7 +141,7 @@ Some examples that will fail if incorrect capitalization is used:
- NGINX (needs all capitals) - NGINX (needs all capitals)
- runit (needs lowercase `r`) - runit (needs lowercase `r`)
Additionally, commands, parameters, values, filenames, etc. must be included in backticks. Additionally, commands, parameters, values, filenames, and so on must be included in backticks.
For example: For example:
- "Change the `needs` keyword in your `.gitlab.yml`..." - "Change the `needs` keyword in your `.gitlab.yml`..."
...@@ -198,7 +201,7 @@ The table below shows what kind of documentation goes where. ...@@ -198,7 +201,7 @@ The table below shows what kind of documentation goes where.
1. `doc/user/group/` should contain all group related documentation. 1. `doc/user/group/` should contain all group related documentation.
1. `doc/user/profile/` should contain all profile related documentation. 1. `doc/user/profile/` should contain all profile related documentation.
Every page you would navigate under `/profile` should have its own document, Every page you would navigate under `/profile` should have its own document,
i.e. `account.md`, `applications.md`, `emails.md`, etc. for example, `account.md`, `applications.md`, or `emails.md`.
1. `doc/user/dashboard/` should contain all dashboard related documentation. 1. `doc/user/dashboard/` should contain all dashboard related documentation.
1. `doc/user/admin_area/` should contain all admin related documentation 1. `doc/user/admin_area/` should contain all admin related documentation
describing what can be achieved by accessing GitLab's admin interface describing what can be achieved by accessing GitLab's admin interface
...@@ -235,7 +238,7 @@ Do not include the same information in multiple places. [Link to a SSOT instead. ...@@ -235,7 +238,7 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
### Structure within documents ### Structure within documents
- Include any and all applicable subsections as described on the [structure and template](structure.md) page. - Include any and all applicable subsections as described on the [structure and template](structure.md) page.
- Structure content in alphabetical order in tables, lists, etc., unless there is - Structure content in alphabetical order in tables, lists, and so on, unless there is
a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence). a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence).
## Language ## Language
...@@ -271,9 +274,9 @@ Do not include the same information in multiple places. [Link to a SSOT instead. ...@@ -271,9 +274,9 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
- Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen." - Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen."
- We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.," - We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.,"
as even native users of English might misunderstand them. as even native users of English might misunderstand them.
- Instead of "i.e.", use "that is." - Instead of "i.e.," use "that is."
- Instead of "e.g.", use "for example," "such as," "for instance," or "like." - Instead of "e.g.," use "for example," "such as," "for instance," or "like."
- Instead of "etc.", either use "and so on" or consider editing it out, since it can be vague. - Instead of "etc.," either use "and so on" or consider editing it out, since it can be vague.
### Contractions ### Contractions
...@@ -332,8 +335,9 @@ as even native users of English might misunderstand them. ...@@ -332,8 +335,9 @@ as even native users of English might misunderstand them.
- [Write in Markdown](#markdown). - [Write in Markdown](#markdown).
- Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text. - Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text.
- Insert an empty line for new paragraphs. - Insert an empty line for new paragraphs.
- Add a new line by ending a line with two spaces. [Using a backslash](../../user/markdown.md#newlines) doesn't work in the docs site.
- Use sentence case for titles, headings, labels, menu items, and buttons. - Use sentence case for titles, headings, labels, menu items, and buttons.
- Insert an empty line between different markups (e.g., after every paragraph, header, list, etc). Example: - Insert an empty line between different markups (for example, after every paragraph, header, list, and so on). Example:
```md ```md
## Header ## Header
...@@ -637,7 +641,7 @@ We include guidance for links in the following categories: ...@@ -637,7 +641,7 @@ We include guidance for links in the following categories:
It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`. It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/). - Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/).
E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`, For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
write `Read more about [GitLab Issue Boards](LINK)`. write `Read more about [GitLab Issue Boards](LINK)`.
### Links to internal documentation ### Links to internal documentation
...@@ -675,7 +679,8 @@ To link to internal documentation: ...@@ -675,7 +679,8 @@ To link to internal documentation:
- `../../issues/tags.md` - `../../issues/tags.md`
- `../../issues/tags.md#stages` - `../../issues/tags.md#stages`
- Use the Markdown extension for the [`/help`](index.md#gitlab-help) section of GitLab. NOTE: **Note**:
Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab.
### Links requiring permissions ### Links requiring permissions
...@@ -721,9 +726,9 @@ To indicate the steps of navigation through the UI: ...@@ -721,9 +726,9 @@ To indicate the steps of navigation through the UI:
- Use the exact word as shown in the UI, including any capital letters as-is. - Use the exact word as shown in the UI, including any capital letters as-is.
- Use bold text for navigation items and the char "greater than" (`>`) as separator - Use bold text for navigation items and the char "greater than" (`>`) as separator
(e.g., `Navigate to your project's **Settings > CI/CD**` ). (for example, `Navigate to your project's **Settings > CI/CD**` ).
- If there are any expandable menus, make sure to mention that the user - If there are any expandable menus, make sure to mention that the user
needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`). needs to expand the tab to find the settings you're referring to (for example, `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
## Images ## Images
...@@ -852,7 +857,7 @@ nicely on different mobile devices. ...@@ -852,7 +857,7 @@ nicely on different mobile devices.
## Code blocks ## Code blocks
- Always wrap code added to a sentence in inline code blocks (`` ` ``). - Always wrap code added to a sentence in inline code blocks (`` ` ``).
E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `only: [master]`. For example, `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, or `only: [master]`.
File names, commands, entries, and anything that refers to code should be added to code blocks. File names, commands, entries, and anything that refers to code should be added to code blocks.
To make things easier for the user, always add a full code block for things that can be To make things easier for the user, always add a full code block for things that can be
useful to copy and paste, as they can easily do it with the button on code blocks. useful to copy and paste, as they can easily do it with the button on code blocks.
...@@ -1197,11 +1202,11 @@ belongs to, says the GitLab version that it became available in, and links to ...@@ -1197,11 +1202,11 @@ belongs to, says the GitLab version that it became available in, and links to
the pricing page in case the user wants to upgrade to a paid tier the pricing page in case the user wants to upgrade to a paid tier
to use that feature. to use that feature.
For example, if I'm a regular user and I'm looking at the docs for a feature I haven't used before, For example, if you're a regular user and you're looking at the docs for a feature you haven't used before,
I can immediately see if that feature is available to me or not. Alternatively, you can immediately see if that feature is available to you or not. Alternatively,
if I have been using a certain feature for a long time and it changed in some way, if you've been using a certain feature for a long time and it changed in some way,
it's important it's important
to me to spot when it changed and what's new in that feature. to be able to spot when it changed and what's new in that feature.
This is even more important as we don't have a perfect process for shipping docs. This is even more important as we don't have a perfect process for shipping docs.
Unfortunately, we still see features without docs and docs without Unfortunately, we still see features without docs and docs without
...@@ -1265,12 +1270,12 @@ badges and tooltips (`<span class="badge-trigger starter">`). When the keyword ...@@ -1265,12 +1270,12 @@ badges and tooltips (`<span class="badge-trigger starter">`). When the keyword
Certain styles should be applied to specific sections. Styles for specific sections are outlined below. Certain styles should be applied to specific sections. Styles for specific sections are outlined below.
### GitLab Restart ### GitLab restart
There are many cases that a restart/reconfigure of GitLab is required. To There are many cases that a restart/reconfigure of GitLab is required. To
avoid duplication, link to the special document that can be found in avoid duplication, link to the special document that can be found in
[`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will [`doc/administration/restart_gitlab.md`](../../administration/restart_gitlab.md).
read like: Usually the text will read like:
```md ```md
Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md) Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
...@@ -1563,8 +1568,3 @@ restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and ...@@ -1563,8 +1568,3 @@ restrict the sign-up e-mail domains of a GitLab instance to `*.example.com` and
```shell ```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "domain_whitelist[]=*.example.com" --data "domain_whitelist[]=example.net" https://gitlab.example.com/api/v4/application/settings
``` ```
[single spaces]: http://www.slate.com/articles/technology/technology/2011/01/space_invaders.html
[gfm]: ../../user/markdown.md#newlines "GitLab flavored markdown documentation"
[ce-1242]: https://gitlab.com/gitlab-org/gitlab-foss/issues/1242
[doc-restart]: ../../administration/restart_gitlab.md "GitLab restart documentation"
...@@ -821,32 +821,30 @@ Footnotes add a link to a note that will be rendered at the end of a Markdown fi ...@@ -821,32 +821,30 @@ Footnotes add a link to a note that will be rendered at the end of a Markdown fi
To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
the note content. the note content.
Regardless of the tag names, the relative order of the reference tags determines the rendered numbering. Regardless of the tag names, the relative order of the reference tags determines the rendered
numbering.
```markdown Reference tags can use letters and other characters. Avoid using lowercase `w` or an underscore
A footnote reference tag looks like this:[^1] (`_`) in footnote tag names until [this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is
resolved.
[^1]: This is the contents of a footnote.
Reference tags can use letters and other characters.[^footnote-note] ```markdown
A footnote reference tag looks like this: [^1]
Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
[^this-name-has-w]: This won't be rendered, because the name contains "w". This reference tag is a mix of letters and numbers. [^footnote-42]
[^this-name-has_]: This won be rendered, because the name contains an underscore. [^1]: This is the text inside a footnote.
[^footnote-42]: This is another footnote.
``` ```
Reference tags can use letters and other characters.[^footnote-note] A footnote reference tag looks like this:[^1]
Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until This reference tag is a mix of letters and numbers.[^footnote-42]
[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
[^this-name-has-w]: This won't be rendered, because the name contains "w". [^1]: This is the text inside a footnote.
[^this-name-has_]: This won't be rendered, because the name contains an underscore. [^footnote-42]: This is another footnote.
### Headers ### Headers
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment