Merge pull request #19285 from dvdksn/markdownlint-add-more-rules

test: add more lint rules for markdown

Author: dvdksn

.markdownlint.json

@@ -1,17 +1,23 @@
 {
   "default": false,
   "hr-style": true,
+  "heading-start-left": true,
+  "single-h1": true,
+  "no-trailing-punctuation": true,
   "no-missing-space-atx": true,
   "no-multiple-space-atx": true,
   "no-missing-space-closed-atx": true,
   "no-multiple-space-closed-atx": true,
   "no-space-in-emphasis": true,
   "no-space-in-code": true,
   "no-space-in-links": true,
+  "no-empty-links": true,
   "ol-prefix": {"style": "ordered"},
   "no-reversed-links": true,
   "reference-links-images": {
     "shortcut_syntax": true
   },
-  "fenced-code-language": true
+  "fenced-code-language": true,
+  "table-pipe-style": true,
+  "table-column-count": true
 }

content/admin/company/users.md

@@ -12,4 +12,4 @@ You can manage users at the company-level in the Docker Admin Console.
 
 ## Manage members on a team
 
-Use Docker Hub to add a member to a team or remove a member from a team. For more details, see [Manage members in Docker Hub](#).
+Use Docker Hub to add a member to a team or remove a member from a team. For more details, see [Manage members in Docker Hub](../organization/members.md#manage-members-on-a-team).

content/build/cache/_index.md

@@ -243,7 +243,7 @@ stages in parallel. Only the instructions in the `site` stage will end up as
 layers in the final image. The entire `git` history doesn't get embedded into
 the final result, which helps keep the image small and secure.
 
-#### Combine commands together wherever possible.
+#### Combine commands together wherever possible
 
 Most Dockerfile commands, and `RUN` commands in particular, can often be joined
 together. For example, instead of using `RUN` like this:

content/compose/gpu-support.md

@@ -31,7 +31,7 @@ This provides more granular control over a GPU reservation as custom values can
 
 For more information on these properties, see the [Compose Deploy Specification](compose-file/deploy.md#devices).
 
-### Example of a Compose file for running a service with access to 1 GPU device:
+### Example of a Compose file for running a service with access to 1 GPU device
 
 ```yaml
 services:

content/compose/release-notes.md

@@ -2865,7 +2865,7 @@ naming scheme accordingly before upgrading.
 ## 1.6.0
 (2016-01-15)
 
-### Major Features:
+### Major Features
 
 -   Compose 1.6 introduces a new format for `docker-compose.yml` which lets
     you define networks and volumes in the Compose file as well as services. It
@@ -2913,7 +2913,7 @@ naming scheme accordingly before upgrading.
     `docker-compose up SERVICE` on a service with dependencies, those are started
     as well.
 
-### New Features:
+### New Features
 
 -   Added a new command `config` which validates and prints the Compose
     configuration after interpolating variables, resolving relative paths, and

content/compose/use-secrets.md

@@ -81,7 +81,7 @@ In the advanced example above:
 >
 > The `_FILE` environment variables demonstrated here are a convention used by some images, including Docker Official Images like [mysql](https://hub.docker.com/_/mysql) and [postgres](https://hub.docker.com/_/postgres).
 
-## Resources:
+## Resources
 
 - [Secrets top-level element](compose-file/09-secrets.md)
-- [Secrets attribute for services top-level element](compose-file/05-services.md#secrets)
+- [Secrets attribute for services top-level element](compose-file/05-services.md#secrets)

content/config/formatting.md

@@ -97,7 +97,7 @@ $ docker inspect --format "{{upper .Name}}" container
 $ docker inspect --format='{{range .NetworkSettings.Networks}}{{println .IPAddress}}{{end}}' container
 ```
 
-# Hint
+## Hint
 
 To find out what data can be printed, show all content as json:
 

content/contribute/style/formatting.md

@@ -9,7 +9,7 @@ toc_max: 2
 
 Readers pay fractionally more attention to headings, bulleted lists, and links, so it's important to ensure the first two to three words in those items "front load" information as much as possible.
 
-### Best practice:
+### Best practice
 
 - Headings and subheadings should let the reader know what they will find on the page.
 - They should describe succinctly and accurately what the content is about.
@@ -21,7 +21,7 @@ Readers pay fractionally more attention to headings, bulleted lists, and links,
 
 Page titles should be action orientated. For example: - _Enable SCIM_ - _Install Docker Desktop_
 
-### Best practice:
+### Best practice
 
 - Make sure the title of your page and the table of contents (TOC) entry matches.
 - If you want to use a ‘:’ in a page title in the table of contents (\_toc.yaml), you must wrap the entire title in “” to avoid breaking the build.
@@ -31,7 +31,7 @@ Page titles should be action orientated. For example: - _Enable SCIM_ - _Install
 
 Images, including screenshots, can help a reader better understand a concept. However, you should use them sparingly as they tend to go out-of-date.
 
-### Best practice:
+### Best practice
 
 - When you take screenshots:
   - Don’t use lorem ipsum text. Try to replicate how someone would use the feature in a real-world scenario, and use realistic text.
@@ -52,7 +52,7 @@ When people follow links, they can often lose their train of thought and fail to
 
 The best links offer readers another way to scan information.
 
-### Best practice:
+### Best practice
 
 - Use plain language that doesn't mislead or promise too much.
 - Be short and descriptive (around five words is best).
@@ -72,7 +72,7 @@ To apply inline code style, wrap the text in a single backtick (`).
 
 For information on how to add code blocks to your content, see [Useful component and formatting examples](../components/code-blocks.md).
 
-### Best practice for commands:
+### Best practice for commands
 
 - Command prompt and shell:
   - For a non-privileged shell, prefix commands in code blocks with the $ prompt symbol.
@@ -89,7 +89,7 @@ For information on how to add code blocks to your content, see [Useful component
   - Use pipes ( \| ) between mutually exclusive arguments.
   - Use three dots ( ... ) after repeated arguments.
 
-### Best practice for code:
+### Best practice for code
 
 - Indent code blocks by 3 spaces when you nest a code block under a list item.
 - Use three dots ( ... ) when you omit code.
@@ -98,7 +98,7 @@ For information on how to add code blocks to your content, see [Useful component
 
 Use callouts to emphasize selected information on a page.
 
-### Best practice:
+### Best practice
 
 - Format the word Warning, Important, or Note in bold. Don't bold the content within the callout.
 - It's good practice to avoid placing a lot of text callouts on one page. They can create a cluttered appearance if used to excess, and you'll diminish their impact.
@@ -110,7 +110,7 @@ Use callouts to emphasize selected information on a page.
 | Important    | Use an Important tag to signal to the reader where actions may cause issues of a lower magnitude.                                                                                   | Yellow               |
 |              | ✅ Example: Update to the Docker Desktop terms                                                                                                                                      |                      |
 | Note         | Use the Note tag for information that may not apply to all readers, or if the information is tangential to a topic.                                                                 | Blue                 |
-|              | ✅ Example: Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone.                                                          |
+|              | ✅ Example: Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone.                                                          |                      |
 
 For information on how to add callouts to your content, see [Useful component and formatting examples](../components/call-outs.md).
 
@@ -149,7 +149,7 @@ Use tables to describe complex information in a straightforward manner.
 
 Note that in many cases, an unordered list is enough to describe a list of items with a single, simple description per item. But, if you have data that’s best described by a matrix, tables are the best choice.
 
-### Best practice:
+### Best practice
 
 - Use sentence case for table headings.
 - To keep tables accessible and scannable, tables shouldn't have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A for ‘not applicable’ or None.
@@ -173,4 +173,4 @@ When you're referring to units of measurement, use the abbreviated form in all c
     | --- | --- |
     | 10 GB | 10GB |
     | 10 GB | 10 gb |
-    | 10 GB | 10 gigabytes |
+    | 10 GB | 10 gigabytes |

content/contribute/style/grammar.md

@@ -13,7 +13,7 @@ An acronym is an abbreviation you would speak as a word, for example, ROM (for r
 
 An initialism is a type of acronym that comprises a group of initial letters used as an abbreviation for a name or expression. If you were using the acronym in a spoken conversation, you would enunciate each letter: H-T-M-L for Hypertext Markup Language.
 
-### Best practice:
+### Best practice
 
 - Spell out lesser-known acronyms or initialisms on first use, then follow with the acronym or initialism in parentheses. After this, throughout the rest of your page or document, use the acronym or initialism alone.
 > ‘You can use single sign-on (SSO) to sign in to Notion. You may need to ask your administrator to enable SSO.’
@@ -26,7 +26,7 @@ An initialism is a type of acronym that comprises a group of initial letters use
 
 Unless you're referring to UI text or user-defined text, you shouldn't add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear.
 
-### Best practice:
+### Best practice
 
 - Don't use bold to refer to a feature name.
 - Use italics sparingly, as this type of formatting can be difficult to read in digital experiences.
@@ -63,7 +63,7 @@ A contraction results from letters being left out from the original word or phra
 
 Following our conversational approach, it's acceptable to use contractions in almost all content types. Just don't get carried away. Too many contractions in a sentence can make it difficult to read.
 
-### Best practice:
+### Best practice
 
 - Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or UI text.
 - Avoid negative contractions (can't, don't, wouldn't, and shouldn't) whenever possible. Try to rewrite your sentence to align with our helpful approach that puts the focus on solutions, not problems.
@@ -79,7 +79,7 @@ When possible, use the month's full name (October 1, 2022). If there are space c
 
 In all UI content and technical documentation, use decimals instead of fractions.
 
-### Best practice:
+### Best practice
 
 - Always carry decimals to at least the hundredth place (33.76).
 - In tables, align decimals on the decimal point.
@@ -89,7 +89,7 @@ In all UI content and technical documentation, use decimals instead of fractions
 
 Lists are a great way to break down complex ideas and make them easier to read and scan.
 
-### Best practice:
+### Best practice
 
 - Bulleted lists should contain relatively few words or short phrases. For most content types, limit the number of items in a list to five.
 - Don’t add commas (,) or semicolons (;) to the ends of list items.
@@ -168,4 +168,4 @@ Don't use parentheses in technical documentation. They can reduce the readabilit
 
 ## Third party documentation
 
-If you are documenting a task that requires the use of a third-party product, link out to the third-party's documentation. Don't copy the content because it might violate copyright. It can also result in an unnecessary maintenance burden of having to keep the docs up-to-date when the third-party changes or updates their product. It is best practice to link to the single source of truth.
+If you are documenting a task that requires the use of a third-party product, link out to the third-party's documentation. Don't copy the content because it might violate copyright. It can also result in an unnecessary maintenance burden of having to keep the docs up-to-date when the third-party changes or updates their product. It is best practice to link to the single source of truth.

content/contribute/style/recommended-words.md

@@ -86,8 +86,12 @@ _In Docker Desktop 4.1 and lower._
 
 What might be easy for you might not be easy for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.
 
+<!-- markdownlint-disable no-trailing-punctuation -->
+
 #### e.g.
 
+<!-- markdownlint-enable no-trailing-punctuation -->
+
 Don't use. Instead, use phrases like `for example` or `such as`.
 
 #### enable
@@ -160,9 +164,9 @@ _Turn on the dark mode toggle._
 
 Use `upgrade` when describing a higher subscription tier
 
-#### vs.
+#### vs
 
-Don't use `vs.` as an abbreviation for versus; instead, use the unabbreviated `versus`.
+Don't use `vs` or `vs.` as an abbreviation for versus; instead, use the unabbreviated `versus`.
 
 #### we
 
@@ -178,4 +182,4 @@ _We created a feature for you to add widgets._
 
 #### wish
 
-Don't use. Use `want` instead.
+Don't use. Use `want` instead.