Merge branch 'docs/refine-markdown-proselint-config' into 'master'

Add refined sample linting configuration

See merge request gitlab-org/gitlab-ce!22827

doc/development/documentation/styleguide.md

@@ -15,10 +15,10 @@ 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.
+  documentation.
 
 NOTE: **Note:**
 **Do not** use capital letters, spaces, or special chars in file names,
@@ -45,10 +45,10 @@ a test that will fail if it spots a new `README.md` file.
 - Capitalize "G" and "L" in GitLab.
 - 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").
+  [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").
 
 ## Formatting
 
@@ -130,9 +130,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 bold text for navigation items and the char `>` 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
-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.
 
 ## Images
 
@@ -147,7 +147,7 @@ needs to expand the tab to find the settings you're referring to.
 - 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.
 
@@ -296,7 +296,7 @@ keyword "only":
 - For GitLab Core: `**[CORE ONLY]**`.
 
 The tier should be ideally added to headers, so that the full badge will be displayed.
-But it can be also mentioned from paragraphs, list items, and table cells. For these cases,
+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.
 E.g., `**[STARTER]**` renders **[STARTER]**, `**[STARTER ONLY]**` renders **[STARTER ONLY]**.
 
@@ -317,7 +317,7 @@ avoid duplication, link to the special document that can be found in
 [`doc/administration/restart_gitlab.md`][doc-restart]. Usually the text will
 read like:
 
-```
+```md
 Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
 for the changes to take effect.
 ```
@@ -404,7 +404,7 @@ low.
 You can use the following fake tokens as examples.
 
 | **Token type**        | **Token value**                                                    |
-| --------------------- | --------------------------------- |
+|:----------------------|:-------------------------------------------------------------------|
 | Private user token    | `9koXpg98eAheJpvBs5tK`                                             |
 | Personal access token | `n671WNGecHugsdEDPsyo`                                             |
 | Application ID        | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
@@ -438,15 +438,15 @@ on this document. Further explanation is given below.
 Use the following table headers to describe the methods. Attributes should
 always be in code blocks using backticks (``` ` ```).
 
-```
+```md
 | Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
+|:----------|:-----|:---------|:------------|
 ```
 
 Rendered example:
 
 | Attribute | Type   | Required | Description         |
-| --------- | ---- | -------- | ----------- |
+|:----------|:-------|:---------|:--------------------|
 | `user`    | string | yes      | The GitLab username |
 
 #### cURL commands
@@ -460,7 +460,7 @@ Rendered example:
   username and password.
 
 | Methods                                    | Description                                           |
-| ------- | ----------- |
+|:-------------------------------------------|:------------------------------------------------------|
 | `-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"` | Use this method as is, whenever authentication needed |
 | `-X POST`                                  | Use this method when creating new objects             |
 | `-X PUT`                                   | Use this method when updating existing objects        |

doc/development/documentation/workflow.md

@@ -7,16 +7,16 @@ description: Learn the process of shipping documentation for GitLab.
 At GitLab, developers contribute new or updated documentation along with their code, but product managers and technical writers also have essential roles in the process.
 
 - Product Managers (PMs): in the issue for all new and updated features,
-PMs include specific documentation requirements that the developer who is
-writing or updating the docs must meet, along with feature descriptions
-and use cases. They call out any specific areas where collaborating with
-a technical writer is recommended, and usually act as the first reviewer
-of the docs.
+  PMs include specific documentation requirements that the developer who is
+  writing or updating the docs must meet, along with feature descriptions
+  and use cases. They call out any specific areas where collaborating with
+  a technical writer is recommended, and usually act as the first reviewer
+  of the docs.
 - Developers: author documentation and merge it on time (up to a week after
-the feature freeze).
+  the feature freeze).
 - Technical Writers: review each issue to ensure PM's requirements are complete,
-help developers with any questions throughout the process, and act as the final
-reviewer of all new and updated docs content before it's merged.
+  help developers with any questions throughout the process, and act as the final
+  reviewer of all new and updated docs content before it's merged.
 
 ## Requirements
 
@@ -112,17 +112,17 @@ and the missed-deliverable due date (the 14th of each month) are both respected.
 The developer should add to the feature MR the documentation containing:
 
 - The [documentation blurb](structure.md#documentation-blurb): copy the
-feature name, overview/description, and use cases from the feature issue
+  feature name, overview/description, and use cases from the feature issue
 - Instructions: write how to use the feature, step by step, with no gaps.
 - [Crosslink for discoverability](structure.md#discoverability): link with
-internal docs and external resources (if applicable)
+  internal docs and external resources (if applicable)
 - Index: link the new doc or the new heading from the higher-level index
-for [discoverability](#discoverability)
+  for [discoverability](#discoverability)
 - [Screenshots](styleguide.md#images): when necessary, add screenshots for:
   - Illustrating a step of the process
   - Indicating the location of a navigation menu
 - Label the MR with `Documentation`, `Deliverable`, `docs-P1`, and assign
-the correct milestone
+  the correct milestone
 - Assign the PM for review
 - When done, mention the `@gl\-docsteam` in the MR asking for review
 - **Due date**: feature freeze date and time
@@ -133,10 +133,10 @@ If the docs aren't being shipped within the feature MR:
 
 - Create a new issue mentioning "docs" or "documentation" in the title (use the Documentation issue description template)
 - Label the issue with: `Documentation`, `Deliverable`, `docs-P1`, `<product-label>`
-(product label == CI/CD, Pages, Prometheus, etc)
+  (product label == CI/CD, Pages, Prometheus, etc)
 - Add the correct milestone
 - Create a new MR for shipping the docs changes and follow the same
-process [described above](#documentation-shipped-in-the-feature-mr)
+  process [described above](#documentation-shipped-in-the-feature-mr)
 - Use the MR description template called "Documentation"
 - Add the same labels and milestone as you did for the issue
 - Assign the PM for review
@@ -162,9 +162,9 @@ The **due date** for **merging** `missed-deliverable` MRs is on the
 
 - **Planning**
   - Once an issue contains a Documentation label and the current milestone, a
-technical writer reviews the Product Manager's documentation requirements
+  technical writer reviews the Product Manager's documentation requirements.
   - Once the documentation requirements are approved, the technical writer can
-work with the developer to discuss any documentation questions and plans/outlines, as needed.
+  work with the developer to discuss any documentation questions and plans/outlines, as needed.
 
 - **Review** - A technical writer must review the documentation for:
   - Clarity
@@ -183,4 +183,3 @@ work with the developer to discuss any documentation questions and plans/outline
   - Describe the difference between new features and feature updates
   - Creating a new doc vs updating an existing doc
 -->
-