Enable linter for Markdown files

.github/workflows/docs.yml

@@ -16,6 +16,14 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+
+      - name: Check links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
         with:
           config-file: .github/workflows/mlc_config.json
+
+      - name: Lint
+        uses: avto-dev/markdown-lint@v1
+        with:
+          args: '**/*.md'
+          config: .github/workflows/lint/markdown.yaml

.github/workflows/lint/markdown.yaml

+default: false # includes/excludes all rules by default
+
+# Heading levels should only increment by one level at a time <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md001>
+MD001: true
+
+# Heading style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md003>
+MD003: true
+
+# Unordered list style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md004>
+MD004: true
+
+# Inconsistent indentation for list items at the same level <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md005>
+MD005: true
+
+# Consider starting bulleted lists at the beginning of the line <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md006>
+MD006: true
+
+# Unordered list indentation <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md007>
+MD007: true
+
+# Trailing spaces <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md009>
+MD009: true
+
+# Hard tabs <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md010>
+MD010: true
+
+# Reversed link syntax <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md011>
+MD011: true
+
+# Multiple consecutive blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md012>
+MD012: true
+
+# Line length <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md013>
+MD013:
+  line_length: 120
+  code_blocks: false
+
+# Dollar signs used before commands without showing output <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md014>
+MD014: false
+
+# No space after hash on atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md018>
+MD018: true
+
+# Multiple spaces after hash on atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md019>
+MD019: true
+
+# No space inside hashes on closed atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md020>
+MD020: true
+
+# Multiple spaces inside hashes on closed atx style heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md021>
+MD021: true
+
+# Headings should be surrounded by blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md022>
+MD022: true
+
+# Headings must start at the beginning of the line <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md023>
+MD023: true
+
+# Multiple headings with the same content <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md024>
+MD024:
+  allow_different_nesting: true
+
+# Multiple top level headings in the same document <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md025>
+MD025: true
+
+# Trailing punctuation in heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md026>
+MD026: true
+
+# Multiple spaces after blockquote symbol <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md027>
+MD027: true
+
+# Blank line inside blockquote <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md028>
+MD028: false
+
+# Ordered list item prefix <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md029>
+MD029:
+  style: 'one'
+
+# Spaces after list markers <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md030>
+MD030: true
+
+# Fenced code blocks should be surrounded by blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md031>
+MD031: true
+
+# Lists should be surrounded by blank lines <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md032>
+MD032: true
+
+# Inline HTML <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md033>
+MD033: true
+
+# Bare URL used <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md034>
+MD034: true
+
+# Horizontal rule style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md035>
+MD035:
+  style: '---'
+
+# Emphasis used instead of a heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md036>
+MD036: true
+
+# Spaces inside emphasis markers <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md037>
+MD037: true
+
+# Spaces inside code span elements <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md038>
+MD038: true
+
+# Spaces inside link text <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md039>
+MD039: true
+
+# Fenced code blocks should have a language specified <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md040>
+MD040: true
+
+# First line in file should be a top level heading <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md041>
+MD041: true
+
+# No empty links <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md042>
+MD042: true
+
+# Required heading structure <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md043>
+MD043: false
+
+# Proper names should have the correct capitalization <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md044>
+MD044:
+  names:
+  - docker-elk
+  - Elasticsearch
+  - Logstash
+  - Kibana
+  - Docker
+  - Compose
+  - macOS
+  code_blocks: false
+
+# Images should have alternate text (alt text) <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md045>
+MD045: true
+
+# Code block style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md046>
+MD046:
+  style: fenced
+
+# Files should end with a single newline character <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md047>
+MD047: true
+
+# Code fence style <https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md048>
+MD048:
+  style: 'backtick'
+
+# Custom rules:
+CHANGELOG-RULE-001: true
+CHANGELOG-RULE-002: true
+CHANGELOG-RULE-003: true
+CHANGELOG-RULE-004: true

README.md

@@ -22,7 +22,8 @@ Based on the official Docker images from Elastic:
 
 Other available stack variants:
 
-* [`tls`](https://github.com/deviantony/docker-elk/tree/tls): TLS encryption enabled in Elasticsearch. _Regularly rebased onto `master`_
+* [`tls`](https://github.com/deviantony/docker-elk/tree/tls): TLS encryption enabled in Elasticsearch. _Regularly
+  rebased onto `master`_
 * [`searchguard`](https://github.com/deviantony/docker-elk/tree/searchguard): Search Guard support
 
 ## Contents
@@ -70,6 +71,7 @@ Other available stack variants:
 interact with the Docker daemon.*
 
 By default, the stack exposes the following ports:
+
 * 5044: Logstash Beats input
 * 5000: Logstash TCP input
 * 9600: Logstash monitoring API
@@ -168,12 +170,12 @@ $ docker-compose exec -T elasticsearch bin/elasticsearch-setup-passwords auto --
 
 Passwords for all 6 built-in users will be randomly generated. Take note of them.
 
-2. Unset the bootstrap password (_optional_)
+1. Unset the bootstrap password (_optional_)
 
 Remove the `ELASTIC_PASSWORD` environment variable from the `elasticsearch` service inside the Compose file
 (`docker-compose.yml`). It is only used to initialize the keystore during the initial startup of Elasticsearch.
 
-3. Replace usernames and passwords in configuration files
+1. Replace usernames and passwords in configuration files
 
 Use the `kibana_system` user (`kibana` for releases <7.8.0) inside the Kibana configuration file
 (`kibana/config/kibana.yml`) and the `logstash_system` user inside the Logstash configuration file
@@ -187,7 +189,7 @@ to create a user with suitable roles.*
 
 See also the [Configuration](#configuration) section below.
 
-4. Restart Kibana and Logstash to apply changes
+1. Restart Kibana and Logstash to apply changes
 
 ```console
 $ docker-compose restart kibana logstash
@@ -198,8 +200,8 @@ security][sec-tutorial].*
 
 ### Injecting data
 
-Give Kibana about a minute to initialize, then access the Kibana web UI by hitting
-[http://localhost:5601](http://localhost:5601) with a web browser and use the following default credentials to log in:
+Give Kibana about a minute to initialize, then access the Kibana web UI by opening <http://localhost:5601> in a web
+browser and use the following credentials to log in:
 
 * user: *elastic*
 * password: *\<your generated elastic password>*
@@ -207,7 +209,6 @@ Give Kibana about a minute to initialize, then access the Kibana web UI by hitti
 Now that the stack is running, you can go ahead and inject some log entries. The shipped Logstash configuration allows
 you to send content via TCP:
 
-
 ```console
 # Using BSD netcat (Debian, Ubuntu, MacOS system, ...)
 $ cat /path/to/logfile.log | nc -q0 localhost 5000
@@ -322,8 +323,8 @@ $ curl -XPOST -D- 'http://localhost:9200/_security/user/elastic/_password' \
 To add plugins to any ELK component you have to:
 
 1. Add a `RUN` statement to the corresponding `Dockerfile` (eg. `RUN logstash-plugin install logstash-filter-json`)
-2. Add the associated plugin code configuration to the service configuration (eg. Logstash input/output)
-3. Rebuild the images using the `docker-compose build` command
+1. Add the associated plugin code configuration to the service configuration (eg. Logstash input/output)
+1. Rebuild the images using the `docker-compose build` command
 
 ### How to enable the provided extensions
 
@@ -402,10 +403,9 @@ If all components get deployed without any error, the following command will sho
 $ docker stack services elk
 ```
 
-*:information_source: To scale Elasticsearch in Swarm mode, configure *zen* to use the DNS name `tasks.elasticsearch`
+*:information_source: To scale Elasticsearch in Swarm mode, configure seed hosts with the DNS name `tasks.elasticsearch`
 instead of `elasticsearch`.*
 
-
 [elk-stack]: https://www.elastic.co/what-is/elk-stack
 [xpack]: https://www.elastic.co/what-is/open-x-pack
 [paid-features]: https://www.elastic.co/subscriptions

extensions/README.md

-Third-party extensions that enable extra integrations with the ELK stack.
+# Extensions
+
+Third-party extensions that enable extra integrations with the Elastic stack.

extensions/apm-server/README.md

@@ -43,15 +43,14 @@ Configuration settings for each supported language are available in the APM docu
 ## Checking connectivity and importing default APM dashboards
 
 1. On the Kibana home page, click `Add APM` under the _Observability_ panel.
-2. Click `Check APM Server status` to confirm the server is up and running.
-3. Click `Check agent status` to verify your agent has registered properly.
-4. Click `Load Kibana objects` to create an index pattern for APM.
-5. Click `Launch APM` to be taken to the APM dashboard.
+1. Click `Check APM Server status` to confirm the server is up and running.
+1. Click `Check agent status` to verify your agent has registered properly.
+1. Click `Load Kibana objects` to create an index pattern for APM.
+1. Click `Launch APM` to be taken to the APM dashboard.
 
 ## See also
 
 [Running APM Server on Docker][apm-docker]
 
-
 [apm-agents]: https://www.elastic.co/guide/en/apm/get-started/current/components.html#_apm_agents
 [apm-docker]: https://www.elastic.co/guide/en/apm/server/current/running-on-docker.html

extensions/curator/README.md

@@ -17,4 +17,4 @@ All configuration files are available in the `config/` directory.
 
 ## Documentation
 
-https://www.elastic.co/guide/en/elasticsearch/client/curator/current/index.html
+[Curator Reference](https://www.elastic.co/guide/en/elasticsearch/client/curator/current/index.html)

extensions/enterprise-search/README.md

@@ -66,7 +66,7 @@ line argument referencing the `enterprise-search-compose.yml` file:
 $ docker-compose -f docker-compose.yml -f extensions/enterprise-search/enterprise-search-compose.yml up
 ```
 
-Allow a few minutes for the stack to start, then open your web browser at the address http://localhost:3002 to see the
+Allow a few minutes for the stack to start, then open your web browser at the address <http://localhost:3002> to see the
 Enterprise Search home page.
 
 Enterprise Search is configured on first boot with the following default credentials:
@@ -122,7 +122,6 @@ Docker container: [Running Enterprise Search Using Docker][enterprisesearch-dock
 
 [Enterprise Search documentation][enterprisesearch-docs]
 
-
 [config-enterprisesearch]: ./config/enterprise-search.yml
 
 [enterprisesearch-encryption]: https://www.elastic.co/guide/en/enterprise-search/current/encryption-keys.html

extensions/logspout/README.md

@@ -14,7 +14,7 @@ $ docker-compose -f docker-compose.yml -f extensions/logspout/logspout-compose.y
 
 In your Logstash pipeline configuration, enable the `udp` input and set the input codec to `json`:
 
-```
+```logstash
 input {
   udp {
     port  => 5000
@@ -25,4 +25,4 @@ input {
 
 ## Documentation
 
-https://github.com/looplab/logspout-logstash
+<https://github.com/looplab/logspout-logstash>