Merge branch 'docs-mdl-rules-update-1' into 'master'

Expand markdown linting rules for docs

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

.mdlrc.style

@@ -5,12 +5,19 @@
 # for more detailed information on the rules and styles.
 
 rule "MD001"
+rule "MD002"
 rule "MD003", :style => :atx
+rule "MD006"
 rule "MD011"
+rule "MD019"
+rule "MD022"
 rule "MD023"
+rule "MD025"
+rule "MD028"
 rule "MD032"
 rule "MD034"
 rule "MD037"
+rule "MD038"
 
 # Should not be used currently:
 

doc/administration/operations/fast_ssh_key_lookup.md

@@ -71,10 +71,10 @@ sudo service sshd reload
 Confirm that SSH is working by removing your user's SSH key in the UI, adding a
 new one, and attempting to pull a repo.
 
-> **Note:** For Omnibus Docker, `AuthorizedKeysCommand` is setup by default in
+NOTE: **Note:** For Omnibus Docker, `AuthorizedKeysCommand` is setup by default in
 GitLab 11.11 and later.
 
-> **Warning:** Do not disable writes until SSH is confirmed to be working
+CAUTION: **Caution:** Do not disable writes until SSH is confirmed to be working
 perfectly, because the file will quickly become out-of-date.
 
 In the case of lookup failures (which are common), the `authorized_keys`

doc/ci/variables/README.md

@@ -484,9 +484,10 @@ Below you can find supported syntax reference:
 
 1. Equality matching using a string
 
-    > Example: `$VARIABLE == "some value"`
+   Examples:
 
-    > Example: `$VARIABLE != "some value"` (introduced in GitLab 11.11)
+   - `$VARIABLE == "some value"`
+   - `$VARIABLE != "some value"` (introduced in GitLab 11.11)
 
    You can use equality operator `==` or `!=` to compare a variable content to a
    string. We support both, double quotes and single quotes to define a string
@@ -495,9 +496,10 @@ Below you can find supported syntax reference:
 
 1. Checking for an undefined value
 
-    > Example: `$VARIABLE == null`
+   Examples:
 
-    > Example: `$VARIABLE != null` (introduced in GitLab 11.11)
+   - `$VARIABLE == null`
+   - `$VARIABLE != null` (introduced in GitLab 11.11)
 
    It sometimes happens that you want to check whether a variable is defined
    or not. To do that, you can compare a variable to `null` keyword, like
@@ -506,9 +508,10 @@ Below you can find supported syntax reference:
 
 1. Checking for an empty variable
 
-    > Example: `$VARIABLE == ""`
+   Examples:
   
-    > Example: `$VARIABLE != ""` (introduced in GitLab 11.11)
+   - `$VARIABLE == ""`
+   - `$VARIABLE != ""` (introduced in GitLab 11.11)
 
    If you want to check whether a variable is defined, but is empty, you can
    simply compare it against an empty string, like `$VAR == ''` or non-empty
@@ -516,16 +519,17 @@ Below you can find supported syntax reference:
 
 1. Comparing two variables
 
-    > Example: `$VARIABLE_1 == $VARIABLE_2`
+   Examples:
 
-    > Example: `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11)
+   - `$VARIABLE_1 == $VARIABLE_2`
+   - `$VARIABLE_1 != $VARIABLE_2` (introduced in GitLab 11.11)
 
    It is possible to compare two variables. This is going to compare values
    of these variables.
 
 1. Variable presence check
 
-    > Example: `$STAGING`
+   Example: `$STAGING`
 
    If you only want to create a job when there is some variable present,
    which means that it is defined and non-empty, you can simply use
@@ -536,9 +540,10 @@ Below you can find supported syntax reference:
 
 1. Pattern matching (introduced in GitLab 11.0)
 
-    > Example: `$VARIABLE =~ /^content.*/`
+   Examples:
 
-    > Example: `$VARIABLE_1 !~ /^content.*/` (introduced in GitLab 11.11)
+   - `$VARIABLE =~ /^content.*/`
+   - `$VARIABLE_1 !~ /^content.*/` (introduced in GitLab 11.11)
 
    It is possible perform pattern matching against a variable and regular
    expression. Expression like this evaluates to truth if matches are found
@@ -549,11 +554,11 @@ Below you can find supported syntax reference:
 
 1. Conjunction / Disjunction ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27925) in GitLab 12.0)
 
-    > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
+   Examples:
 
-    > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
-
-    > Example: `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+   - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"`
+   - `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3`
+   - `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3`
 
    It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise
    supported syntax may be used in a conjunctive or disjunctive statement.

doc/development/testing_guide/end_to_end/quick_start_guide.md

@@ -110,7 +110,7 @@ end
 ```
 
 > Notice that the test itself is simple. The most challenging part is the creation of the application state, which will be covered later.
-
+>
 > The exemplified test case's MVC is not enough for the change to be merged, but it helps to build up the test logic. The reason is that we do not want to use locators directly in the tests, and tests **must** use [Page Objects] before they can be merged. This way we better separate the responsibilities, where the Page Objects encapsulate elements and methods that allow us to interact with pages, while the spec files describe the test cases in more business-related language.
 
 Below are the steps that the test covers:
@@ -211,7 +211,7 @@ A pre-condition for the entire test suite is defined in the `before :context` bl
 
 > For our test suite, due to the need of the tests being completely independent of each other, we won't use the `before :context` block. The `before :context` block would make the tests dependent on each other because the first test changes the label of the issue, and the second one depends on the `'animal::fox'` label being set.
 
-> **Tip:** In case of a test suite with only one `it` block it's ok to use only the `before` block (see below) with all the test's pre-conditions.
+TIP: **Tip:** In case of a test suite with only one `it` block it's ok to use only the `before` block (see below) with all the test's pre-conditions.
 
 #### `before`
 
@@ -274,11 +274,11 @@ end
 In the `before` block we create all the application state needed for the tests to run. We do that by using the `Runtime::Browser.visit` method to go to the login page, by performing a `sign_in_using_credentials` from the `Login` Page Object, by fabricating resources via APIs (`issue`, and `Resource::Label`), and by using the `issue.visit!` to visit the issue page.
 
 > A project is created in the background by creating the `issue` resource.
-
+>
 > When creating the [Resources], notice that when calling the `fabricate_via_api` method, we pass some attribute:values, like `title`, and `labels` for the `issue` resource; and `project` and `title` for the `label` resource.
-
+>
 > What's important to understand here is that by creating the application state mostly using the public APIs we save a lot of time in the test suite setup stage.
-
+>
 > Soon we will cover the use of the already existing resources' methods and the creation of your own `fabricate_via_api` methods for resources where this is still not available, but first, let's optimize our implementation.
 
 ### 6. Optimization
@@ -362,7 +362,7 @@ First, in the [issue resource](https://gitlab.com/gitlab-org/gitlab-ee/blob/d358
 Add the following `attribute :id` and `attribute :labels` right above the [`attribute :title`](https://gitlab.com/gitlab-org/gitlab-ee/blob/d3584e80b4236acdf393d815d604801573af72cc/qa/qa/resource/issue.rb#L15).
 
 > This line is needed to allow for the issue fabrication, and for labels to be automatically added to the issue when fabricating it via API.
-
+>
 > We add the attributes above the existing attribute to keep them alphabetically organized.
 
 Then, let's initialize an instance variable for labels to allow an empty array as default value when such information is not passed during the resource fabrication, since this optional. [Between the attributes and the `fabricate!` method](https://gitlab.com/gitlab-org/gitlab-ee/blob/1a1f1408728f19b2aa15887cd20bddab7e70c8bd/qa/qa/resource/issue.rb#L18), add the following:
@@ -437,7 +437,7 @@ By defining the `resource_web_url(resource)` method, we override the one from th
 
 By defining the `api_get_path` method, we **would** allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single label, but since there's no path available for that in the publich API, we raise a `NotImplementedError` instead.
 
-By defining the `api_post_path` method, we allow for the [`ApiFabricator `](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new label in a specific project.
+By defining the `api_post_path` method, we allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new label in a specific project.
 
 By defining the `api_post_body` method, we we allow for the [`ApiFabricator.api_post`](https://gitlab.com/gitlab-org/gitlab-ee/blob/a9177ca1812bac57e2b2fa4560e1d5dd8ffac38b/qa/qa/resource/api_fabricator.rb#L68) method to know which data to send when making the `POST` request.
 
@@ -580,7 +580,7 @@ filter_output = search_field_tag search_id, nil, class: "dropdown-input-field",
 
 > `data-qa-*` data attributes and CSS classes starting with `qa-` are used solely for the purpose of QA and testing.
 > By defining these, we add **testability** to the application.
-
+>
 > When defining a data attribute like: `qa_selector: 'labels_block'`, it should match the element definition: `element :labels_block`. We use a [sanity test](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa/qa/page#how-did-we-solve-fragile-tests-problem) to check that defined elements have their respective selectors in the specified views.
 
 #### Updates in the `QA::Page::Base` class
@@ -599,8 +599,6 @@ This method receives an element (`name`) and the `keys` that it will send to tha
 
 As you might remember, in the Issue Page Object we call this method like this: `send_keys_to_element(:dropdown_input_field, [label, :enter])`.
 
-___
-
 With that, you should be able to start writing end-to-end tests yourself. *Congratulations!*
 
 [Page Objects]: page_objects.md

doc/development/what_requires_downtime.md

@@ -140,7 +140,7 @@ done without requiring downtime. However, this does require that any application
 changes are deployed _first_. Thus, changing the constraints of a column should
 happen in a post-deployment migration.
 NOTE: Avoid using `change_column` as it produces inefficient query because it re-defines
-the whole column type. For example, to add a NOT NULL constraint, prefer `change_column_null `
+the whole column type. For example, to add a NOT NULL constraint, prefer `change_column_null`
 
 ## Changing Column Types
 

doc/user/group/bulk_editing/index.md

@@ -5,15 +5,14 @@
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12719) for merge
   requests in GitLab [GitLab Premium](https://about.gitlab.com/pricing/) 12.2.
 
-> NOTE: **Note:**
->
-> - A permission level of `Reporter` or higher is required in order to manage issues.
-> - A permission level of `Developer` or higher is required in order to manage merge requests.
-
 Milestones can be updated simultaneously across multiple issues or merge requests by using the bulk editing feature.
 
 ![Bulk editing](img/bulk-editing.png)
 
+NOTE: **Note:**
+A permission level of `Reporter` or higher is required in order to manage issues, and
+a permission level of `Developer` or higher is required in order to manage merge requests.
+
 To bulk update group issue or merge request milestones:
 
 1. Navigate to the issues or merge requests list.

doc/user/project/issues/related_issues.md

@@ -19,7 +19,7 @@ Issues from a different project require additional information like the
 group and the project name. For example:
 
 - same project: `#44`
-- same group: `project#44 `
+- same group: `project#44`
 - different group: `group/project#44`
 
 Valid references will be added to a temporary list that you can review.