Docs: updates docs development guidelines
This commit is contained in:
Marcia Ramos
Achilleas Pipinellis
parent
f5e3ce5ed6
commit
3cfdb0acb2
3 changed files with 463 additions and 323 deletions
|
|
@ -41,9 +41,11 @@ how to structure GitLab docs.
|
|||
|
||||
## Markdown and styles
|
||||
|
||||
Currently GitLab docs use [Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) as the [markdown](../../user/markdown.md) engine.
|
||||
[GitLab docs](https://gitlab.com/gitlab-com/gitlab-docs) uses [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown)
|
||||
as markdown engine. Check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
|
||||
for a complete Kramdown reference.
|
||||
|
||||
All the docs follow the [documentation style guidelines](styleguide.md). See [Linting](#linting) for help to follow the guidelines.
|
||||
Follow the [documentation style guidelines](styleguide.md) strictly.
|
||||
|
||||
## Documentation directory structure
|
||||
|
||||
|
|
@ -198,6 +200,11 @@ redirect_to: '../path/to/file/README.md'
|
|||
|
||||
It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`.
|
||||
|
||||
NOTE: **Note:**
|
||||
This redirection method will not provide a redirect fallback on GitLab `/help`. When using
|
||||
it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that
|
||||
land on the doc via `/help`.
|
||||
|
||||
### Redirections for pages with Disqus comments
|
||||
|
||||
If the documentation page being relocated already has any Disqus comments,
|
||||
|
|
@ -223,145 +230,6 @@ 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,
|
||||
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`](#proselint)
|
||||
- [`markdownlint`](#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` and `misc.phrasal_adjectives` checks will reduce
|
||||
noise. The following sample `proselint` configuration disables these checks:
|
||||
|
||||
```json
|
||||
{
|
||||
"checks": {
|
||||
"typography.symbols": false,
|
||||
"misc.phrasal_adjectives": 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.
|
||||
- Allow the flexibility of using some inline HTML.
|
||||
|
||||
```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,
|
||||
"no-inline-html": {
|
||||
"allowed_elements": [
|
||||
"table",
|
||||
"tbody",
|
||||
"tr",
|
||||
"td",
|
||||
"ul",
|
||||
"ol",
|
||||
"li",
|
||||
"br",
|
||||
"img",
|
||||
"a",
|
||||
"strong",
|
||||
"i",
|
||||
"div"
|
||||
]
|
||||
},
|
||||
"hr-style": { "style": "---" },
|
||||
"fenced-code-language": false
|
||||
}
|
||||
```
|
||||
|
||||
For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be
|
||||
placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For
|
||||
example, `~/.markdownlintrc`.
|
||||
|
||||
## Testing
|
||||
|
||||
We treat documentation as code, thus have implemented some testing.
|
||||
Currently, the following tests are in place:
|
||||
|
||||
1. `docs lint`: Check that all internal (relative) links work correctly and
|
||||
that all cURL examples in API docs use the full switches. It's recommended
|
||||
to [check locally](#previewing-locally) before pushing to GitLab by executing the command
|
||||
`bundle exec nanoc check internal_links` on your local
|
||||
[`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory.
|
||||
1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only):
|
||||
When you submit a merge request to GitLab Community Edition (CE),
|
||||
there is this additional job that runs against Enterprise Edition (EE)
|
||||
and checks if your changes can apply cleanly to the EE codebase.
|
||||
If that job fails, read the instructions in the job log for what to do next.
|
||||
As CE is merged into EE once a day, it's important to avoid merge conflicts.
|
||||
Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
|
||||
essential to avoid them.
|
||||
|
||||
## Branch naming
|
||||
|
||||
If your contribution contains **only** documentation changes, you can speed up
|
||||
|
|
@ -377,15 +245,6 @@ choices:
|
|||
If your branch name matches any of the above, it will run only the docs
|
||||
tests. If it doesn't, the whole test suite will run (including docs).
|
||||
|
||||
## Danger bot
|
||||
|
||||
GitLab uses [danger bot](https://github.com/danger/danger) for some elements in
|
||||
code review. For docs changes in merge requests, the following actions are taken:
|
||||
|
||||
1. Whenever a change under `/doc` is made, the bot leaves a comment for the
|
||||
author to mention `@gl-docsteam`, so that the docs can be properly
|
||||
reviewed.
|
||||
|
||||
## Merge requests for GitLab documentation
|
||||
|
||||
Before getting started, make sure you read the introductory section
|
||||
|
|
@ -428,105 +287,6 @@ Follow this [method for cherry-picking from CE to EE](../automatic_ce_ee_merge.m
|
|||
additionally to the CE MR. If there are many EE-only changes though, start a new MR
|
||||
to EE only.
|
||||
|
||||
## Previewing the changes live
|
||||
|
||||
NOTE: **Note:**
|
||||
To preview your changes to documentation locally, follow this
|
||||
[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
|
||||
|
||||
The live preview is currently enabled for the following projects:
|
||||
|
||||
- <https://gitlab.com/gitlab-org/gitlab-ce>
|
||||
- <https://gitlab.com/gitlab-org/gitlab-ee>
|
||||
- <https://gitlab.com/gitlab-org/gitlab-runner>
|
||||
|
||||
If your branch contains only documentation changes, you can use
|
||||
[special branch names](#branch-naming) to avoid long running pipelines.
|
||||
|
||||
For [docs-only changes](#branch-naming), the review app is run automatically.
|
||||
For all other branches, you can use the manual `review-docs-deploy-manual` job
|
||||
in your merge request. You will need at least Maintainer permissions to be able
|
||||
to run it. In the mini pipeline graph, you should see an `>>` icon. Clicking on it will
|
||||
reveal the `review-docs-deploy-manual` job. Hit the play button for the job to start.
|
||||
|
||||
|
||||
|
||||
NOTE: **Note:**
|
||||
You will need to push a branch to those repositories, it doesn't work for forks.
|
||||
|
||||
The `review-docs-deploy*` job will:
|
||||
|
||||
1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
|
||||
project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`,
|
||||
where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for
|
||||
CE, etc.
|
||||
1. Trigger a cross project pipeline and build the docs site with your changes
|
||||
|
||||
After a few minutes, the Review App will be deployed and you will be able to
|
||||
preview the changes. The docs URL can be found in two places:
|
||||
|
||||
- In the merge request widget
|
||||
- In the output of the `review-docs-deploy*` job, which also includes the
|
||||
triggered pipeline so that you can investigate whether something went wrong
|
||||
|
||||
TIP: **Tip:**
|
||||
Someone that has no merge rights to the CE/EE projects (think of forks from
|
||||
contributors) will not be able to run the manual job. In that case, you can
|
||||
ask someone from the GitLab team who has the permissions to do that for you.
|
||||
|
||||
NOTE: **Note:**
|
||||
Make sure that you always delete the branch of the merge request you were
|
||||
working on. If you don't, the remote docs branch won't be removed either,
|
||||
and the server where the Review Apps are hosted will eventually be out of
|
||||
disk space.
|
||||
|
||||
### Troubleshooting review apps
|
||||
|
||||
In case the review app URL returns 404, follow these steps to debug:
|
||||
|
||||
1. **Did you follow the URL from the merge request widget?** If yes, then check if
|
||||
the link is the same as the one in the job output.
|
||||
1. **Did you follow the URL from the job output?** If yes, then it means that
|
||||
either the site is not yet deployed or something went wrong with the remote
|
||||
pipeline. Give it a few minutes and it should appear online, otherwise you
|
||||
can check the status of the remote pipeline from the link in the job output.
|
||||
If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
|
||||
|
||||
### Technical aspects
|
||||
|
||||
If you want to know the hot details, here's what's really happening:
|
||||
|
||||
1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
|
||||
1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
|
||||
script with the `deploy` flag, which in turn:
|
||||
1. Takes your branch name and applies the following:
|
||||
- The slug of the branch name is used to avoid special characters since
|
||||
ultimately this will be used by NGINX.
|
||||
- The `preview-` prefix is added to avoid conflicts if there's a remote branch
|
||||
with the same name that you created in the merge request.
|
||||
- The final branch name is truncated to 42 characters to avoid filesystem
|
||||
limitations with long branch names (> 63 chars).
|
||||
1. The remote branch is then created if it doesn't exist (meaning you can
|
||||
re-run the manual job as many times as you want and this step will be skipped).
|
||||
1. A new cross-project pipeline is triggered in the docs project.
|
||||
1. The preview URL is shown both at the job output and in the merge request
|
||||
widget. You also get the link to the remote pipeline.
|
||||
1. In the docs project, the pipeline is created and it
|
||||
[skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
|
||||
to lower the build time.
|
||||
1. Once the docs site is built, the HTML files are uploaded as artifacts.
|
||||
1. A specific Runner tied only to the docs project, runs the Review App job
|
||||
that downloads the artifacts and uses `rsync` to transfer the files over
|
||||
to a location where NGINX serves them.
|
||||
|
||||
The following GitLab features are used among others:
|
||||
|
||||
- [Manual actions](../../ci/yaml/README.md#manual-actions)
|
||||
- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html)
|
||||
- [Review Apps](../../ci/review_apps/index.md)
|
||||
- [Artifacts](../../ci/yaml/README.md#artifacts)
|
||||
- [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects)
|
||||
|
||||
## GitLab `/help`
|
||||
|
||||
Every GitLab instance includes the documentation, which is available from `/help`
|
||||
|
|
@ -678,5 +438,250 @@ date: 2017-02-01
|
|||
|
||||
Use the [writing method](https://about.gitlab.com/handbook/product/technical-writing/#writing-method) defined by the Technical Writing team.
|
||||
|
||||
## Previewing the changes live
|
||||
|
||||
NOTE: **Note:**
|
||||
To preview your changes to documentation locally, follow this
|
||||
[development guide](https://gitlab.com/gitlab-com/gitlab-docs/blob/master/README.md#development-when-contributing-to-gitlab-documentation) or [these instructions for GDK](https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/gitlab_docs.md).
|
||||
|
||||
The live preview is currently enabled for the following projects:
|
||||
|
||||
- <https://gitlab.com/gitlab-org/gitlab-ce>
|
||||
- <https://gitlab.com/gitlab-org/gitlab-ee>
|
||||
- <https://gitlab.com/gitlab-org/gitlab-runner>
|
||||
|
||||
If your branch contains only documentation changes, you can use
|
||||
[special branch names](#branch-naming) to avoid long running pipelines.
|
||||
|
||||
For [docs-only changes](#branch-naming), the review app is run automatically.
|
||||
For all other branches, you can use the manual `review-docs-deploy-manual` job
|
||||
in your merge request. You will need at least Maintainer permissions to be able
|
||||
to run it. In the mini pipeline graph, you should see an `>>` icon. Clicking on it will
|
||||
reveal the `review-docs-deploy-manual` job. Hit the play button for the job to start.
|
||||
|
||||
|
||||
|
||||
NOTE: **Note:**
|
||||
You will need to push a branch to those repositories, it doesn't work for forks.
|
||||
|
||||
The `review-docs-deploy*` job will:
|
||||
|
||||
1. Create a new branch in the [gitlab-docs](https://gitlab.com/gitlab-com/gitlab-docs)
|
||||
project named after the scheme: `$DOCS_GITLAB_REPO_SUFFIX-$CI_ENVIRONMENT_SLUG`,
|
||||
where `DOCS_GITLAB_REPO_SUFFIX` is the suffix for each product, e.g, `ce` for
|
||||
CE, etc.
|
||||
1. Trigger a cross project pipeline and build the docs site with your changes
|
||||
|
||||
After a few minutes, the Review App will be deployed and you will be able to
|
||||
preview the changes. The docs URL can be found in two places:
|
||||
|
||||
- In the merge request widget
|
||||
- In the output of the `review-docs-deploy*` job, which also includes the
|
||||
triggered pipeline so that you can investigate whether something went wrong
|
||||
|
||||
TIP: **Tip:**
|
||||
Someone that has no merge rights to the CE/EE projects (think of forks from
|
||||
contributors) will not be able to run the manual job. In that case, you can
|
||||
ask someone from the GitLab team who has the permissions to do that for you.
|
||||
|
||||
NOTE: **Note:**
|
||||
Make sure that you always delete the branch of the merge request you were
|
||||
working on. If you don't, the remote docs branch won't be removed either,
|
||||
and the server where the Review Apps are hosted will eventually be out of
|
||||
disk space.
|
||||
|
||||
### Troubleshooting review apps
|
||||
|
||||
In case the review app URL returns 404, follow these steps to debug:
|
||||
|
||||
1. **Did you follow the URL from the merge request widget?** If yes, then check if
|
||||
the link is the same as the one in the job output.
|
||||
1. **Did you follow the URL from the job output?** If yes, then it means that
|
||||
either the site is not yet deployed or something went wrong with the remote
|
||||
pipeline. Give it a few minutes and it should appear online, otherwise you
|
||||
can check the status of the remote pipeline from the link in the job output.
|
||||
If the pipeline failed or got stuck, drop a line in the `#docs` chat channel.
|
||||
|
||||
### Technical aspects
|
||||
|
||||
If you want to know the in-depth details, here's what's really happening:
|
||||
|
||||
1. You manually run the `review-docs-deploy` job in a CE/EE merge request.
|
||||
1. The job runs the [`scripts/trigger-build-docs`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/scripts/trigger-build-docs)
|
||||
script with the `deploy` flag, which in turn:
|
||||
1. Takes your branch name and applies the following:
|
||||
- The slug of the branch name is used to avoid special characters since
|
||||
ultimately this will be used by NGINX.
|
||||
- The `preview-` prefix is added to avoid conflicts if there's a remote branch
|
||||
with the same name that you created in the merge request.
|
||||
- The final branch name is truncated to 42 characters to avoid filesystem
|
||||
limitations with long branch names (> 63 chars).
|
||||
1. The remote branch is then created if it doesn't exist (meaning you can
|
||||
re-run the manual job as many times as you want and this step will be skipped).
|
||||
1. A new cross-project pipeline is triggered in the docs project.
|
||||
1. The preview URL is shown both at the job output and in the merge request
|
||||
widget. You also get the link to the remote pipeline.
|
||||
1. In the docs project, the pipeline is created and it
|
||||
[skips the test jobs](https://gitlab.com/gitlab-com/gitlab-docs/blob/8d5d5c750c602a835614b02f9db42ead1c4b2f5e/.gitlab-ci.yml#L50-55)
|
||||
to lower the build time.
|
||||
1. Once the docs site is built, the HTML files are uploaded as artifacts.
|
||||
1. A specific Runner tied only to the docs project, runs the Review App job
|
||||
that downloads the artifacts and uses `rsync` to transfer the files over
|
||||
to a location where NGINX serves them.
|
||||
|
||||
The following GitLab features are used among others:
|
||||
|
||||
- [Manual actions](../../ci/yaml/README.md#manual-actions)
|
||||
- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html)
|
||||
- [Review Apps](../../ci/review_apps/index.md)
|
||||
- [Artifacts](../../ci/yaml/README.md#artifacts)
|
||||
- [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects)
|
||||
|
||||
## Testing
|
||||
|
||||
We treat documentation as code, thus have implemented some testing.
|
||||
Currently, the following tests are in place:
|
||||
|
||||
1. `docs lint`: Check that all internal (relative) links work correctly and
|
||||
that all cURL examples in API docs use the full switches. It's recommended
|
||||
to [check locally](#previewing-locally) before pushing to GitLab by executing the command
|
||||
`bundle exec nanoc check internal_links` on your local
|
||||
[`gitlab-docs`](https://gitlab.com/gitlab-com/gitlab-docs) directory.
|
||||
1. [`ee_compat_check`](../automatic_ce_ee_merge.md#avoiding-ce-gt-ee-merge-conflicts-beforehand) (runs on CE only):
|
||||
When you submit a merge request to GitLab Community Edition (CE),
|
||||
there is this additional job that runs against Enterprise Edition (EE)
|
||||
and checks if your changes can apply cleanly to the EE codebase.
|
||||
If that job fails, read the instructions in the job log for what to do next.
|
||||
As CE is merged into EE once a day, it's important to avoid merge conflicts.
|
||||
Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is
|
||||
essential to avoid them.
|
||||
|
||||
### 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`](#proselint)
|
||||
- [`markdownlint`](#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` and `misc.phrasal_adjectives` checks will reduce
|
||||
noise. The following sample `proselint` configuration disables these checks:
|
||||
|
||||
```json
|
||||
{
|
||||
"checks": {
|
||||
"typography.symbols": false,
|
||||
"misc.phrasal_adjectives": 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.
|
||||
- Allow the flexibility of using some inline HTML.
|
||||
|
||||
```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,
|
||||
"no-inline-html": {
|
||||
"allowed_elements": [
|
||||
"table",
|
||||
"tbody",
|
||||
"tr",
|
||||
"td",
|
||||
"ul",
|
||||
"ol",
|
||||
"li",
|
||||
"br",
|
||||
"img",
|
||||
"a",
|
||||
"strong",
|
||||
"i",
|
||||
"div"
|
||||
]
|
||||
},
|
||||
"hr-style": { "style": "---" },
|
||||
"fenced-code-language": false
|
||||
}
|
||||
```
|
||||
|
||||
For [`markdownlint`](https://github.com/DavidAnson/markdownlint/), this configuration must be
|
||||
placed in a [valid location](https://github.com/igorshubovych/markdownlint-cli#configuration). For
|
||||
example, `~/.markdownlintrc`.
|
||||
|
||||
## Danger bot
|
||||
|
||||
GitLab uses [danger bot](https://github.com/danger/danger) for some elements in
|
||||
code review. For docs changes in merge requests, whenever a change under `/doc`
|
||||
is made, the bot leaves a comment for the author to mention `@gl-docsteam`, so
|
||||
that the docs can be properly reviewed.
|
||||
|
||||
[gitlab-map]: https://gitlab.com/gitlab-org/gitlab-design/raw/master/production/resources/gitlab-map.png
|
||||
[graffle]: https://gitlab.com/gitlab-org/gitlab-design/blob/d8d39f4a87b90fb9ae89ca12dc565347b4900d5e/production/resources/gitlab-map.graffle
|
||||
|
|
|
|||
|
|
@ -10,17 +10,15 @@ GitLab documentation. Check the
|
|||
|
||||
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).
|
||||
For help adhering to the guidelines, see [linting](index.md#linting).
|
||||
|
||||
## Files
|
||||
|
||||
- [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.
|
||||
- [Markdown](../../user/markdown.md): use the GitLab Flavored Markdown in the
|
||||
documentation.
|
||||
|
||||
NOTE: **Note:**
|
||||
DANGER: **Attention:**
|
||||
**Do not** use capital letters, spaces, or special chars in file names,
|
||||
branch names, directory names, headings, or in anything that generates a path.
|
||||
|
||||
|
|
@ -28,65 +26,144 @@ NOTE: **Note:**
|
|||
**Do not** create new `README.md` files, name them `index.md` instead. There's
|
||||
a test that will fail if it spots a new `README.md` file.
|
||||
|
||||
### 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)
|
||||
in October, 2018.
|
||||
|
||||
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
|
||||
gem will support all [GFM markup](../../user/markdown.md) in the future. For now,
|
||||
use regular markdown markup, following the rules on this style guide. For a complete
|
||||
Kramdown reference, check the [GiLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/).
|
||||
Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in
|
||||
[`/help`](#gitlab-help).
|
||||
|
||||
## Content
|
||||
|
||||
- Make sure that the documentation is added in the correct
|
||||
[directory](index.md#documentation-directory-structure), linked from its
|
||||
higher-level index, and linked from other related pages.
|
||||
- Do not duplicate information.
|
||||
- Be brief and clear.
|
||||
- Unless there's a logical reason not to, structure the document in alphabetical order
|
||||
(headings, tables, and lists).
|
||||
- Write in US English.
|
||||
- Capitalize "G" and "L" in GitLab.
|
||||
- Use title case when referring to [features](https://about.gitlab.com/features/) or
|
||||
[products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
|
||||
Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies
|
||||
(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.").
|
||||
|
||||
## Text
|
||||
|
||||
- Split up long lines (wrap text), this makes it much easier to review and edit. Only
|
||||
double line breaks are shown as a full line break in [GitLab markdown][gfm].
|
||||
80-100 characters is a good line length.
|
||||
- Make sure that the documentation is added in the correct
|
||||
[directory](index.md#documentation-directory-structure) and that
|
||||
there's a link to it somewhere useful.
|
||||
- Do not duplicate information.
|
||||
- Be brief and clear.
|
||||
- Unless there's a logical reason not to, add documents in alphabetical order.
|
||||
- Write in US English.
|
||||
- Use [single spaces][] instead of double spaces.
|
||||
- Jump a line between different markups (e.g., after every paragraph, header, list, etc)
|
||||
- Capitalize "G" and "L" in GitLab.
|
||||
double line breaks are shown as a full line break by creating new paragraphs.
|
||||
80-100 characters is the recommended line length.
|
||||
- Use sentence case for titles, headings, labels, menu items, and buttons.
|
||||
- Use title case when referring to [features](https://about.gitlab.com/features/) or
|
||||
[products](https://about.gitlab.com/pricing/) (e.g., GitLab Runner, Geo,
|
||||
Issue Boards, GitLab Core, Git, Prometheus, Kubernetes, etc), and methods or methodologies
|
||||
(e.g., Continuous Integration, Continuous Deployment, Scrum, Agile, etc). Note that
|
||||
some features are also objects (e.g. "Merge Requests" and "merge requests").
|
||||
- Jump a line between different markups (e.g., after every paragraph, header, list, etc). Example:
|
||||
|
||||
## Formatting
|
||||
|
||||
- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
|
||||
- Use undescore (`_`) for text in italics (`_italic_`).
|
||||
- Put an empty line between different markups. For example:
|
||||
```md
|
||||
## Header
|
||||
|
||||
Paragraph.
|
||||
|
||||
- List item
|
||||
- List item
|
||||
- List item 1
|
||||
- List item 2
|
||||
```
|
||||
|
||||
### Punctuation
|
||||
## Emphasis
|
||||
|
||||
For punctuation rules, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
|
||||
- Use double asterisks (`**`) to mark a word or text in bold (`**bold**`).
|
||||
- Use undescore (`_`) for text in italics (`_italic_`).
|
||||
- Use greater than (`>`) for blockquotes.
|
||||
|
||||
### Ordered and unordered lists
|
||||
## Punctuation
|
||||
|
||||
- Use dashes (`-`) for unordered lists instead of asterisks (`*`).
|
||||
- Use the number one (`1`) for ordered lists.
|
||||
Check the general punctuation rules for the GitLab documentation on the table below.
|
||||
Check specific punctuation rules for [list items](#list-items) below.
|
||||
|
||||
| Rule | Example |
|
||||
| ---- | ------- |
|
||||
| Always end full sentences with a period. | _For a complete overview, read through this document._|
|
||||
| Always add a space after a period when beginning a new sentence | _For a complete overview, check this doc. For other references, check out this guide._ |
|
||||
| Do not use double spaces. | --- |
|
||||
| Do not use tabs for indentation. Use spaces instead. You can configure your code editor to output spaces instead of tabs when pressing the tab key. | --- |
|
||||
| Use serial commas ("Oxford commas") before the final 'and/or' in a list. | _You can create new issues, merge requests, and milestones._ |
|
||||
| Always add a space before and after dashes when using it in a sentence (for replacing a comma, for example). | _You should try this - or not._ |
|
||||
| Always use lowercase after a colon. | _Related Issues: a way to create a relationship between issues._ |
|
||||
|
||||
## List items
|
||||
|
||||
- Always start list items with a capital letter.
|
||||
- Always leave a blank line before and after a list.
|
||||
- Begin a line with spaces (not tabs) to denote a subitem.
|
||||
- To nest subitems, indent them with two spaces.
|
||||
- To nest code blocks, indent them with four spaces.
|
||||
- Only use ordered lists when their items describe a sequence of steps to follow.
|
||||
|
||||
**Markup:**
|
||||
|
||||
- Use dashes (`- `) for unordered lists instead of asterisks (`* `).
|
||||
- Use the number one (`1`) for each item in an ordered list.
|
||||
When rendered, the list items will appear with sequential numbering.
|
||||
|
||||
**Punctuation:**
|
||||
|
||||
- Do not add commas (`,`) or semicolons (`;`) to the end of a list item.
|
||||
- Only add periods to the end of a list item if the item consists of a complete sentence. The [definition of full sentence](https://www2.le.ac.uk/offices/ld/resources/writing/grammar/grammar-guides/sentence) is: _"a complete sentence always contains a verb, expresses a complete idea, and makes sense standing alone"_.
|
||||
- Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period.
|
||||
- Separate list items from explanatory text with a colon (`:`). For example:
|
||||
|
||||
```md
|
||||
The list is as follows:
|
||||
|
||||
- First item: This explains the first item.
|
||||
- Second item: This explains the second item.
|
||||
- First item: this explains the first item.
|
||||
- Second item: this explains the second item.
|
||||
```
|
||||
- For further guidance on punctuation in bullet lists, please refer to the [GitLab UX guide](https://design.gitlab.com/content/punctuation/).
|
||||
|
||||
**Examples:**
|
||||
|
||||
Do:
|
||||
|
||||
- First list item
|
||||
- Second list item
|
||||
- Third list item
|
||||
|
||||
Don't:
|
||||
|
||||
- First list item
|
||||
- Second list item
|
||||
- Third list item.
|
||||
|
||||
Do:
|
||||
|
||||
- Let's say this is a complete sentence.
|
||||
- Let's say this is also a complete sentence.
|
||||
- Not a complete sentence.
|
||||
|
||||
Don't:
|
||||
|
||||
- Let's say this is a complete sentence.
|
||||
- Let's say this is also a complete sentence.
|
||||
- Not a complete sentence
|
||||
|
||||
## Quotes
|
||||
|
||||
Valid for markdown content only, not for frontmatter entries:
|
||||
|
||||
- Standard quotes: double quotes (`"`). Example: "This is wrapped in double quotes".
|
||||
- Quote within a quote: double quotes (`"`) wrap single quotes (`'`). Example: "I am 'quoting' something within a quote".
|
||||
|
||||
For other punctuation rules, please refer to the
|
||||
[GitLab UX guide](https://design.gitlab.com/content/punctuation/).
|
||||
|
||||
## Headings
|
||||
|
||||
- Add **only one H1** in each document, by adding `#` at the beginning of
|
||||
it (when using markdown). The `h1` will be the document `<title>`.
|
||||
- Start with an h2 (`##`), and respect the order h2 > h3 > h4 > h5 > h6.
|
||||
Never skip the hierarchy level, such as h2 > h4
|
||||
- Start with an `h2` (`##`), and respect the order `h2` > `h3` > `h4` > `h5` > `h6`.
|
||||
Never skip the hierarchy level, such as `h2` > `h4`
|
||||
- Avoid putting numbers in headings. Numbers shift, hence documentation anchor
|
||||
links shift too, which eventually leads to dead links. If you think it is
|
||||
compelling to add numbers in headings, make sure to at least discuss it with
|
||||
|
|
@ -96,21 +173,19 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
|
|||
- Avoid adding things that show ephemeral statuses. For example, if a feature is
|
||||
considered beta or experimental, put this info in a note, not in the heading.
|
||||
- When introducing a new document, be careful for the headings to be
|
||||
grammatically and syntactically correct. Mention one or all
|
||||
of the following GitLab members for a review: `@axil` or `@marcia`.
|
||||
grammatically and syntactically correct. Mention an [assigned technical writer (TW)](https://about.gitlab.com/handbook/product/categories/)
|
||||
for review.
|
||||
This is to ensure that no document with wrong heading is going
|
||||
live without an audit, thus preventing dead links and redirection issues when
|
||||
corrected.
|
||||
- Leave exactly one new line after a heading.
|
||||
- Do not use links in headings.
|
||||
- Add the corresponding [product badge](#product-badges) according to the tier the feature belongs.
|
||||
|
||||
## Links
|
||||
|
||||
- Use the regular inline link markdown markup `[Text](https://example.com)`.
|
||||
It's easier to read, review, and maintain.
|
||||
- If there's a link that repeats several times through the same document,
|
||||
you can use `[Text][identifier]` and at the bottom of the section or the
|
||||
document add: `[identifier]: https://example.com`, in which case, we do
|
||||
encourage you to also add an alternative text: `[identifier]: https://example.com "Alternative text"` that appears when hovering your mouse on a link.
|
||||
- Use inline link markdown markup `[Text](https://example.com)`.
|
||||
It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
|
||||
- To link to internal documentation, use relative links, not full URLs. Use `../` to
|
||||
navigate tp high-level directories, and always add the file name `file.md` at the
|
||||
end of the link with the `.md` extension, not `.html`.
|
||||
|
|
@ -128,11 +203,12 @@ For punctuation rules, please refer to the [GitLab UX guide](https://design.gitl
|
|||
|
||||
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 bold text for navigation items and the char `>` as separator
|
||||
(e.g., `Navigate to your project's **Settings > CI/CD**` ).
|
||||
- Use bold text for navigation items and the char "greater than" (`>`) as separator
|
||||
(e.g., `Navigate to your project's **Settings > CI/CD**` ).
|
||||
- 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.
|
||||
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
|
||||
|
||||
|
|
@ -141,13 +217,13 @@ To indicate the steps of navigation through the UI:
|
|||
names with the name of the document that they will be included in. For
|
||||
example, if there is a document called `twitter.md`, then a valid image name
|
||||
could be `twitter_login_screen.png`.
|
||||
- Images should have a specific, non-generic name that will differentiate them.
|
||||
- Images should have a specific, non-generic name that will differentiate and describe them properly.
|
||||
- Keep all file names in lower case.
|
||||
- Consider using PNG images instead of JPEG.
|
||||
- Compress all images with <https://tinypng.com/> or similar tool.
|
||||
- Compress gifs with <https://ezgif.com/optimize> or similar tool.
|
||||
- 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).
|
||||
- The GitLab docs do not support videos yet.
|
||||
|
||||
|
|
@ -164,13 +240,39 @@ Inside the document:
|
|||
- If a heading is placed right after an image, always add three dashes (`---`)
|
||||
between the image and the heading.
|
||||
|
||||
## Code blocks
|
||||
|
||||
- Always wrap code added to a sentence in inline code blocks (``` ` ```).
|
||||
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.
|
||||
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.
|
||||
- For regular code blocks, always use a highlighting class corresponding to the
|
||||
language for better readability. Examples:
|
||||
|
||||
```md
|
||||
```ruby
|
||||
Ruby code
|
||||
```
|
||||
|
||||
```js
|
||||
JavaScript code
|
||||
```
|
||||
|
||||
```md
|
||||
Markdown code
|
||||
```
|
||||
```
|
||||
|
||||
- For a complete reference on code blocks, check the [Kramdown guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/#code-blocks).
|
||||
|
||||
## Alert boxes
|
||||
|
||||
Whenever you want to call the attention to a particular sentence,
|
||||
use the following markup for highlighting.
|
||||
|
||||
_Note that the alert boxes only work for one paragraph only. Multiple paragraphs,
|
||||
lists, headers, etc will not render correctly._
|
||||
lists, headers, etc will not render correctly. For multiple lines, use blockquotes instead._
|
||||
|
||||
### Note
|
||||
|
||||
|
|
@ -234,6 +336,31 @@ which renders in docs.gitlab.com to:
|
|||
|
||||
If the text spans across multiple lines it's OK to split the line.
|
||||
|
||||
For multiple paragraphs, use the symbol `>` before every line:
|
||||
|
||||
```md
|
||||
> This is the first paragraph.
|
||||
>
|
||||
> This is the second paragraph.
|
||||
>
|
||||
> - This is a list item
|
||||
> - Second item in the list
|
||||
>
|
||||
> ### This is an `h3`
|
||||
```
|
||||
|
||||
Which renders to:
|
||||
|
||||
> This is the first paragraph.
|
||||
>
|
||||
> This is the second paragraph.
|
||||
>
|
||||
> - This is a list item
|
||||
> - Second item in the list
|
||||
>
|
||||
> ### This is an `h3`
|
||||
>{:.no_toc}
|
||||
|
||||
## Specific sections and terms
|
||||
|
||||
To mention and/or reference specific terms in GitLab, please follow the styles
|
||||
|
|
@ -290,18 +417,18 @@ feature availability:
|
|||
To exclude GitLab.com tiers (when the feature is not available in GitLab.com), add the
|
||||
keyword "only":
|
||||
|
||||
- For GitLab Core: `**[CORE ONLY]**`.
|
||||
- For GitLab Starter: `**[STARTER ONLY]**`.
|
||||
- For GitLab Premium: `**[PREMIUM ONLY]**`.
|
||||
- For GitLab Ultimate: `**[ULTIMATE ONLY]**`.
|
||||
- For GitLab Core: `**[CORE ONLY]**`.
|
||||
|
||||
The tier should be ideally added to headers, so that the full badge will be displayed.
|
||||
However, it can be also mentioned from paragraphs, list items, and table cells. For these cases,
|
||||
the tier mention will be represented by an orange question mark.
|
||||
the tier mention will be represented by an orange question mark that will show the tiers on hover.
|
||||
E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**.
|
||||
|
||||
The absence of tiers' mentions mean that the feature is available in GitLab Core,
|
||||
GitLab.com Free, and higher tiers.
|
||||
GitLab.com Free, and all higher tiers.
|
||||
|
||||
#### How it works
|
||||
|
||||
|
|
@ -348,8 +475,8 @@ prefer to document it in the CE docs to avoid duplication.
|
|||
|
||||
Configuration settings include:
|
||||
|
||||
- Settings that touch configuration files in `config/`.
|
||||
- NGINX settings and settings in `lib/support/` in general.
|
||||
1. Settings that touch configuration files in `config/`.
|
||||
1. NGINX settings and settings in `lib/support/` in general.
|
||||
|
||||
When there is a list of steps to perform, usually that entails editing the
|
||||
configuration file and reconfiguring/restarting GitLab. In such case, follow
|
||||
|
|
@ -386,13 +513,13 @@ the style below as a guide:
|
|||
|
||||
In this case:
|
||||
|
||||
- before each step list the installation method is declared in bold
|
||||
- three dashes (`---`) are used to create a horizontal line and separate the
|
||||
- Before each step list the installation method is declared in bold
|
||||
- Three dashes (`---`) are used to create a horizontal line and separate the
|
||||
two methods
|
||||
- the code blocks are indented one or more spaces under the list item to render
|
||||
- The code blocks are indented one or more spaces under the list item to render
|
||||
correctly
|
||||
- different highlighting languages are used for each config in the code block
|
||||
- the [references](#references) guide is used for reconfigure/restart
|
||||
- Different highlighting languages are used for each config in the code block
|
||||
- The [references](#references) guide is used for reconfigure/restart
|
||||
|
||||
### Fake tokens
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,11 @@
|
|||
# Markdown
|
||||
# GitLab Markdown
|
||||
|
||||
This markdown guide is valid for GitLab's system markdown entries and files.
|
||||
This markdown guide is **valid for GitLab's system markdown entries and files**.
|
||||
It is not valid for the [GitLab documentation website](https://docs.gitlab.com)
|
||||
nor [GitLab's main website](https://about.gitlab.com), as they both use
|
||||
[Kramdown](https://kramdown.gettalong.org) as their markdown engine.
|
||||
The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown).
|
||||
Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference._
|
||||
|
||||
## GitLab Flavored Markdown (GFM)
|
||||
|
||||
|
|
@ -8,21 +13,21 @@ GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specifi
|
|||
|
||||
You can use GFM in the following areas:
|
||||
|
||||
- comments
|
||||
- issues
|
||||
- merge requests
|
||||
- milestones
|
||||
- snippets (the snippet must be named with a `.md` extension)
|
||||
- wiki pages
|
||||
- markdown documents inside the repository
|
||||
- Comments
|
||||
- Issues
|
||||
- Merge requests
|
||||
- Milestones
|
||||
- Snippets (the snippet must be named with a `.md` extension)
|
||||
- Wiki pages
|
||||
- Markdown documents inside repositories
|
||||
|
||||
You can also use other rich text files in GitLab. You might have to install a
|
||||
dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information.
|
||||
|
||||
> **Notes:**
|
||||
>
|
||||
> For the best result, we encourage you to check this document out as rendered
|
||||
> by GitLab itself: [markdown.md]
|
||||
> For the best result, we encourage you to check this document out as [rendered
|
||||
> by GitLab itself](markdown.md).
|
||||
>
|
||||
> As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown
|
||||
processing of all new issues, merge requests, comments, and other Markdown content
|
||||
|
|
@ -30,6 +35,9 @@ in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the
|
|||
repositories are also processed with CommonMark. Older content in issues/comments
|
||||
are still processed using the [Redcarpet Ruby library][redcarpet].
|
||||
>
|
||||
> The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108)
|
||||
in October 2018.
|
||||
>
|
||||
> _Where there are significant differences, we will try to call them out in this document._
|
||||
|
||||
### Transitioning to CommonMark
|
||||
|
|
|
|||
Loading…
Reference in a new issue