Add linting section to documentation guidelines
This commit is contained in:
parent
912d068dc6
commit
5e583dc62f
|
@ -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'
|
||||||
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.
|
||||||
- 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
|
||||||
|
|
||||||
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
|
||||||
|
|
Loading…
Reference in New Issue