Commit b7b7d014 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'docs/fix-styleguide' into 'master'

Fix broken markdown and other lint problems

See merge request gitlab-org/gitlab-ce!24208
parents 8dd97b5a 868d8ec6
...@@ -15,7 +15,7 @@ For programmatic help adhering to the guidelines, see [linting](index.md#linting ...@@ -15,7 +15,7 @@ For programmatic help adhering to the guidelines, see [linting](index.md#linting
## Files ## Files
- [Directory structure](index.md#location-and-naming-documents): place the docs - [Directory structure](index.md#location-and-naming-documents): place the docs
in the correct location. in the correct location.
- [Documentation files](index.md#documentation-files): name the files accordingly. - [Documentation files](index.md#documentation-files): name the files accordingly.
DANGER: **Attention:** DANGER: **Attention:**
...@@ -29,7 +29,7 @@ a test that will fail if it spots a new `README.md` file. ...@@ -29,7 +29,7 @@ a test that will fail if it spots a new `README.md` file.
### Markdown ### Markdown
The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108)
in October, 2018. in October 2018.
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
gem will support all [GFM markup](../../user/markdown.md) in the future. For now, gem will support all [GFM markup](../../user/markdown.md) in the future. For now,
...@@ -45,38 +45,38 @@ yield a useful result, and ensuring content is helpful and easy to consume. ...@@ -45,38 +45,38 @@ yield a useful result, and ensuring content is helpful and easy to consume.
- What to include: - What to include:
- Any and all helpful information, processes, and tips for implementing, - Any and all helpful information, processes, and tips for implementing,
using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot)
for this information. for this information.
- 'Risky' or niche problem-solving steps. There is no reason to withhold these or - 'Risky' or niche problem-solving steps. There is no reason to withhold these or
store them elsewhere; simply include them along with the rest of the docs including all necessary store them elsewhere; simply include them along with the rest of the docs including all necessary
detail, such as specific warnings and caveats about potential ramifications. detail, such as specific warnings and caveats about potential ramifications.
- Any content types/sources, if relevant to users or admins. You can freely - Any content types/sources, if relevant to users or admins. You can freely
include presentations, videos, etc.; no matter who it was originally written for, include presentations, videos, etc.; no matter who it was originally written for,
if it is helpful to any of our audiences, we can include it. If an outside source if it is helpful to any of our audiences, we can include it. If an outside source
that's under copyright, rephrase, or summarize and link out; do not copy and paste. that's under copyright, rephrase, or summarize and link out; do not copy and paste.
- All applicable subsections as described on the [structure and template](structure.md) page, - All applicable subsections as described on the [structure and template](structure.md) page,
with files organized in the [correct directory](index.md#documentation-directory-structure). with files organized in the [correct directory](index.md#documentation-directory-structure).
- To ensure discoverability, link to each doc from its higher-level index page and other related pages. - To ensure discoverability, link to each doc from its higher-level index page and other related pages.
- When referencing other GitLab products and features, link to their - When referencing other GitLab products and features, link to their
respective docs; when referencing third-party products or technologies, respective docs; when referencing third-party products or technologies,
link out to their external sites, documentation, and resources. link out to their external sites, documentation, and resources.
- Do not duplicate information. - Do not duplicate information.
- Structure content in alphabetical order in tables, lists, etc., unless there is - Structure content in alphabetical order in tables, lists, etc., unless there is
a logical reason not to (for example, when mirroring the UI or an ordered sequence). a logical reason not to (for example, when mirroring the UI or an ordered sequence).
## Language ## Language
- Use inclusive language and avoid jargon, as well as uncommon - Use inclusive language and avoid jargon, as well as uncommon
words. The docs should be clear and easy to understand. words. The docs should be clear and easy to understand.
- Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me"). - Write in the 3rd person (use "we", "you", "us", "one", instead of "I" or "me").
- Be clear, concise, and stick to the goal of the doc. - Be clear, concise, and stick to the goal of the doc.
- Write in US English. - Write in US English.
- Capitalize "G" and "L" in GitLab. - Capitalize "G" and "L" in GitLab.
- Use title case when referring to [features](https://about.gitlab.com/features/) or - Use title case when referring to [features](https://about.gitlab.com/features/) or
[products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo, [products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies
(e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that (e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that
some features are also objects (e.g. "GitLab's Merge Requests support X." and "Create a new merge request for Z."). some features are also objects (e.g. "GitLab's Merge Requests support X." and "Create a new merge request for Z.").
## Text ## Text
...@@ -127,9 +127,9 @@ Check specific punctuation rules for [list items](#list-items) below. ...@@ -127,9 +127,9 @@ Check specific punctuation rules for [list items](#list-items) below.
**Markup:** **Markup:**
- Use dashes (`- `) for unordered lists instead of asterisks (`* `). - Use dashes (`-`) for unordered lists instead of asterisks (`*`).
- Use the number one (`1`) for each item in an ordered list. - Use the number one (`1`) for each item in an ordered list.
When rendered, the list items will appear with sequential numbering. When rendered, the list items will appear with sequential numbering.
**Punctuation:** **Punctuation:**
...@@ -226,12 +226,11 @@ For other punctuation rules, please refer to the ...@@ -226,12 +226,11 @@ For other punctuation rules, please refer to the
To indicate the steps of navigation through the UI: 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**` ). (e.g., `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 (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
## Images ## Images
...@@ -246,7 +245,7 @@ needs to expand the tab to find the settings you're referring to (e.g., `Navigat ...@@ -246,7 +245,7 @@ needs to expand the tab to find the settings you're referring to (e.g., `Navigat
- Compress all images with <https://tinypng.com/> or similar tool. - Compress all images with <https://tinypng.com/> or similar tool.
- Compress gifs with <https://ezgif.com/optimize> or similar tool. - Compress gifs with <https://ezgif.com/optimize> or similar tool.
- Images should be used (only when necessary) to _illustrate_ the description - Images should be used (only when necessary) to _illustrate_ the description
of a process, not to _replace_ it. of a process, not to _replace_ it.
- Max image size: 100KB (gifs included). - Max image size: 100KB (gifs included).
- The GitLab docs do not support videos yet. - The GitLab docs do not support videos yet.
...@@ -266,12 +265,12 @@ Inside the document: ...@@ -266,12 +265,12 @@ Inside the document:
## 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`. E.g., `.gitlab-ci.yml`, `git add .`, `CODEOWNERS`, `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.
- For regular code blocks, always use a highlighting class corresponding to the - For regular code blocks, always use a highlighting class corresponding to the
language for better readability. Examples: language for better readability. Examples:
```md ```md
```ruby ```ruby
...@@ -592,12 +591,12 @@ on this document. Further explanation is given below. ...@@ -592,12 +591,12 @@ on this document. Further explanation is given below.
The following can be used as a template to get started: The following can be used as a template to get started:
```md ````md
## Descriptive title ## Descriptive title
One or two sentence description of what endpoint does. One or two sentence description of what endpoint does.
``` ```text
METHOD /endpoint METHOD /endpoint
``` ```
...@@ -609,7 +608,7 @@ METHOD /endpoint ...@@ -609,7 +608,7 @@ METHOD /endpoint
Example request: Example request:
```sh ```sh
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/endpoint?parameters' curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/endpoint?parameters'
``` ```
Example response: Example response:
...@@ -620,8 +619,7 @@ Example response: ...@@ -620,8 +619,7 @@ Example response:
} }
] ]
``` ```
````
```
### Fake tokens ### Fake tokens
......
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