Commit b5c96502 authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'docs/linting-section' into 'master'

Add linting section to documentation guidelines

See merge request gitlab-org/gitlab-ce!21849
parents 191f235b 5e583dc6
...@@ -43,13 +43,13 @@ how to structure GitLab docs. ...@@ -43,13 +43,13 @@ how to structure GitLab docs.
Currently GitLab docs use Redcarpet as [markdown](../../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. Currently GitLab docs use Redcarpet as [markdown](../../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
All the docs follow the [documentation style guidelines](styleguide.md). All the docs follow the [documentation style guidelines](styleguide.md). See [Linting](#linting) for help to follow the guidelines.
## Documentation directory structure ## Documentation directory structure
The documentation is structured based on the GitLab UI structure itself, The documentation is structured based on the GitLab UI structure itself,
separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user),
[`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). [`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development).
In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation,
all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent.
...@@ -223,6 +223,108 @@ redirect_from: 'https://docs.gitlab.com/my-old-location/README.html' ...@@ -223,6 +223,108 @@ redirect_from: 'https://docs.gitlab.com/my-old-location/README.html'
Note: it is necessary to include the file name in the `redirect_from` URL, Note: it is necessary to include the file name in the `redirect_from` URL,
even if it's `index.html` or `README.html`. even if it's `index.html` or `README.html`.
## Linting
To help adhere to the [documentation style guidelines](styleguide.md), and to improve the content
added to documentation, consider locally installing and running documentation linters. This will
help you catch common issues before raising merge requests for review of documentation.
The following are some suggested linters you can install locally and sample configuration:
- `proselint`
- `markdownlint`
NOTE: **Note:**
This list does not limit what other linters you can add to your local documentation writing
toolchain.
### `proselint`
`proselint` checks for common problems with English prose. It provides a
[plethora of checks](http://proselint.com/checks/) that are helpful for technical writing.
`proselint` can be used [on the command line](http://proselint.com/utility/), either on a single
Markdown file or on all Markdown files in a project. For example, to run `proselint` on all
documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce), run the
following commands from within the `gitlab-ce` project:
```sh
cd doc
proselint **/*.md
```
`proselint` can also be run from within editors using plugins. For example, the following plugins
are available:
- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-proselint)
- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=PatrykPeszko.vscode-proselint)
- [Others](https://github.com/amperser/proselint#plugins-for-other-software)
#### Sample `proselint` configuration
All of the checks are good to use. However, excluding the `typography.symbols` checks might reduce
noise. The following sample `proselint` configuration disables the `typography.symbols` checks:
```json
{
"checks": {
"typography.symbols": false
}
}
```
A file with `proselint` configuration must be placed in a
[valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`.
### `markdownlint`
`markdownlint` checks that certain rules ([example](https://github.com/DavidAnson/markdownlint/blob/master/README.md#rules--aliases))
are followed for Markdown syntax. Our [style guidelines](styleguide.md) elaborate on which choices
must be made when selecting Markdown syntax for GitLab documentation and this tool helps
catch deviations from those guidelines.
`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
either on a single Markdown file or on all Markdown files in a project. For example, to run
`markdownlint` on all documentation in the [`gitlab-ce` project](https://gitlab.com/gitlab-org/gitlab-ce),
run the following commands from within the `gitlab-ce` project:
```sh
cd doc
markdownlint **/*.md
```
`markdownlint` can also be run from within editors using plugins. For example, the following plugins
are available:
- [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
- [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
- [Others](https://github.com/DavidAnson/markdownlint#related)
#### Sample `markdownlint` configuration
The following sample `markdownlint` configuration modifies the available default rules to:
- Adhere to the [style guidelines](styleguide.md).
- Apply conventions found in the GitLab documentation.
```json
{
"default": true,
"header-style": { "style": "atx" },
"ul-style": { "style": "dash" },
"line-length": false,
"no-trailing-punctuation": false,
"ol-prefix": { "style": "one" },
"blanks-around-fences": false,
"hr-style": { "style": "---" },
"fenced-code-language": false
}
```
For [`markdownlint`](https://gitahub.com/DavidAnson/markdownlint/), this configuration must be
placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For
example, `~/.markdownlintrc`.
## Testing ## Testing
We treat documentation as code, thus have implemented some testing. We treat documentation as code, thus have implemented some testing.
...@@ -278,7 +380,6 @@ for GitLab Team members. ...@@ -278,7 +380,6 @@ for GitLab Team members.
- Label the MR `Documentation` - Label the MR `Documentation`
- Assign the correct milestone (see note below) - Assign the correct milestone (see note below)
NOTE: **Note:** NOTE: **Note:**
If the release version you want to add the documentation to has already been If the release version you want to add the documentation to has already been
frozen or released, use the label `Pick into X.Y` to get it merged into frozen or released, use the label `Pick into X.Y` to get it merged into
......
...@@ -10,6 +10,8 @@ GitLab documentation. Check the ...@@ -10,6 +10,8 @@ GitLab documentation. Check the
Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). Check the GitLab handbook for the [writing styles guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines).
For 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
......
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