test: add more lint rules for markdown

.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.

content/desktop/extensions-sdk/design/design-guidelines.md

@@ -12,7 +12,7 @@ Here is a simple checklist to go through when creating your extension:
 - Is it easy to get help when needed?
 
 
-## Create a consistent experience with Docker Desktop.
+## Create a consistent experience with Docker Desktop
 
 Use the [Docker Material UI Theme](https://www.npmjs.com/package/@docker/docker-mui-theme) and the [Docker Extensions Styleguide](https://www.figma.com/file/U7pLWfEf6IQKUHLhdateBI/Docker-Design-Guidelines?node-id=1%3A28771) to ensure that your extension feels like it is part of Docker Desktop to create a seamless experience for users.
 
@@ -68,4 +68,4 @@ When creating your extension, ensure that first time users of the extension and
 
 - Explore our [design principles](design-principles.md).
 - Take a look at our [UI styling guidelines](index.md).
-- Learn how to [publish your extension](../extensions/index.md).
+- Learn how to [publish your extension](../extensions/index.md).

content/desktop/faqs/releases.md

@@ -12,6 +12,6 @@ New releases are available roughly every month, unless there are critical fixes
 
 Previously you had to manage this yourself. Now, it happens automatically as a side effect of all users being on the latest version.
 
-### My colleague has got a new version but I haven’t got it yet.
+### My colleague has got a new version but I haven’t got it yet
 
 Sometimes we may roll out a new version gradually over a few days. Therefore, if you wait, it will turn up soon. Alternatively, you can select **Check for Updates** from the Docker menu to jump the queue and get the latest version immediately.

content/desktop/hardened-desktop/settings-management/configure.md

@@ -147,18 +147,18 @@ The following `admin-settings.json` code and table provides an example of the re
 | `configurationFileVersion`        |   |Specifies the version of the configuration file format.    |
 | `exposeDockerAPIOnTCP2375` | <span class="badge badge-info">Windows only</span>| Exposes the Docker API on a specified port. If `value` is set to true, the Docker API is exposed on port 2375. Note: This is unauthenticated and should only be enabled if protected by suitable firewall rules.|
 | `proxy` |   |If `mode` is set to `system` instead of `manual`, Docker Desktop gets the proxy values from the system and ignores and values set for `http`, `https` and `exclude`. Change `mode` to `manual` to manually configure proxy servers. If the proxy port is custom, specify it in the `http` or `https` property, for example `"https": "http://myotherproxy.com:4321"`. The `exclude` property specifies a comma-separated list of hosts and domains to bypass the proxy. |
-&nbsp; &nbsp; &nbsp; &nbsp;`windowsDockerdPort`  | <span class="badge badge-info">Windows only</span> | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port. The default value is -1 which disables the option. Note: This is available for Windows containers only. |
+| &nbsp; &nbsp; &nbsp; &nbsp;`windowsDockerdPort`  | <span class="badge badge-info">Windows only</span> | Exposes Docker Desktop's internal proxy locally on this port for the Windows Docker daemon to connect to. If it is set to 0, a random free port is chosen. If the value is greater than 0, use that exact value for the port. The default value is -1 which disables the option. Note: This is available for Windows containers only. |
 | `enhancedContainerIsolation`  |  | If `value` is set to true, Docker Desktop runs all containers as unprivileged, via the Linux user-namespace, prevents them from modifying sensitive configurations inside the Docker Desktop VM, and uses other advanced techniques to isolate them. For more information, see [Enhanced Container Isolation](../enhanced-container-isolation/index.md).|
 | &nbsp; &nbsp; &nbsp; &nbsp;`dockerSocketMount` |  | By default, enhanced container isolation blocks bind-mounting the Docker Engine socket into containers (e.g., `docker run -v /var/run/docker.sock:/var/run/docker.sock ...`). This allows admins to relax this in a controlled way. See [ECI Configuration](../enhanced-container-isolation/config.md) for more info. |
 | &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; `imageList` |  | Indicates which container images are allowed to bind-mount the Docker Engine socket. |
 | &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; `commandList` |  | Restricts the commands that containers can issue via the bind-mounted Docker Engine socket. |
 | `linuxVM` |   |Parameters and settings related to Linux VM options - grouped together here for convenience. |
-| &nbsp; &nbsp; &nbsp; &nbsp;`wslEngineEnabled`  | <span class="badge badge-info">Windows only</span> | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=<backend name>` flag.
+| &nbsp; &nbsp; &nbsp; &nbsp;`wslEngineEnabled`  | <span class="badge badge-info">Windows only</span> | If `value` is set to true, Docker Desktop uses the WSL 2 based engine. This overrides anything that may have been set at installation using the `--backend=<backend name>` flag. |
 | &nbsp;&nbsp; &nbsp; &nbsp;`dockerDaemonOptions`|  |If `value` is set to true, it overrides the options in the Docker Engine config file. See the [Docker Engine reference](/engine/reference/commandline/dockerd/#daemon-configuration-file). Note that for added security, a few of the config attributes may be overridden when Enhanced Container Isolation is enabled. |
 | &nbsp;&nbsp; &nbsp; &nbsp;`vpnkitCIDR` |  |Overrides the network range used for vpnkit DHCP/DNS for `*.docker.internal`  |
 |`kubernetes`|  | If `enabled` is set to true, a Kubernetes single-node cluster is started when Docker Desktop starts. If `showSystemContainers` is set to true, Kubernetes containers are displayed in the UI and when you run `docker ps`.  `imagesRepository` allows you to specify which repository Docker Desktop pulls the Kubernetes images from. For example, `"imagesRepository": "registry-1.docker.io/docker"`.  |
 | `windowsContainers` |  | Parameters and settings related to `windowsContainers` options - grouped together here for convenience.                  |
-| &nbsp; &nbsp; &nbsp; &nbsp;`dockerDaemonOptions` |  | Overrides the options in the Linux daemon config file. See the [Docker Engine reference](/engine/reference/commandline/dockerd/#daemon-configuration-file).|                                |
+| &nbsp; &nbsp; &nbsp; &nbsp;`dockerDaemonOptions` |  | Overrides the options in the Linux daemon config file. See the [Docker Engine reference](/engine/reference/commandline/dockerd/#daemon-configuration-file).|
 |`disableUpdate`|  |If `value` is set to true, checking for and notifications about Docker Desktop updates is disabled.|
 |`analyticsEnabled`|  |If `value` is set to false, Docker Desktop doesn't send usage statistics to Docker. |
 |`extensionsEnabled`|  |If `value` is set to false, Docker extensions are disabled. |