458: Markdown linter as a local npm script & Git Action execution (#503)

Author: Mohammed Munir Abdi

.github/workflows/linting.yaml

@@ -0,0 +1,18 @@
+name: Markdown Linter
+on: [pull_request, push]
+permissions:
+  contents: read
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout markdown
+        uses: actions/checkout@v4.2.0
+      - name: Lint markdown
+        uses: DavidAnson/markdownlint-cli2-action@v17
+        continue-on-error: true
+        with:
+          config: '.markdownlint.yml'
+          globs: |
+            docs/*.md
+            !examples/*.md

.markdownlint.yml

@@ -0,0 +1,140 @@
+default: false
+
+# MD001/heading-increment : Heading levels should only increment by one level at a time : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md001.md
+MD001: true
+
+# MD003/heading-style : Heading style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md003.md
+MD003:
+  style: "consistent"
+
+# MD004/ul-style : Unordered list style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md004.md
+MD004:
+  style: "consistent"
+
+# MD005/list-indent : Inconsistent indentation for list items at the same level : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md005.md
+MD005: true
+
+# MD007/ul-indent : Unordered list indentation : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md007.md
+MD007:
+  indent: 4
+
+# MD009/no-trailing-spaces : Trailing spaces : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md009.md
+MD009: true
+
+# MD010/no-hard-tabs : Hard tabs : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md010.md
+MD010: true
+
+# MD011/no-reversed-links : Reversed link syntax : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md011.md
+MD011: true
+
+# MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md012.md
+MD012: true
+
+# MD014/commands-show-output : Dollar signs used before commands without showing output : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md014.md
+MD014: true
+
+# MD018/no-missing-space-atx : No space after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md018.md
+MD018: true
+
+# MD019/no-multiple-space-atx : Multiple spaces after hash on atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md019.md
+MD019: true
+
+# MD020/no-missing-space-closed-atx : No space inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md020.md
+MD020: true
+
+# MD021/no-multiple-space-closed-atx : Multiple spaces inside hashes on closed atx style heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md021.md
+MD021: true
+
+# MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md022.md
+MD022: true
+
+# MD023/heading-start-left : Headings must start at the beginning of the line : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md023.md
+MD023: true
+
+# MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md024.md
+MD024:
+  siblings_only: true
+
+# MD025/single-title/single-h1 : Multiple top-level headings in the same document : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md025.md
+MD025: true
+
+# MD026/no-trailing-punctuation : Trailing punctuation in heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md026.md
+MD026: true
+
+# MD027/no-multiple-space-blockquote : Multiple spaces after blockquote symbol : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md027.md
+MD027: true
+
+# MD028/no-blanks-blockquote : Blank line inside blockquote : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md028.md
+MD028: true
+
+# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md029.md
+MD029:
+  style: "ordered"
+
+# MD030/list-marker-space : Spaces after list markers : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md030.md
+MD030:
+  ul_single: 1
+  ol_single: 1
+  ul_multi: 3
+  ol_multi: 2
+
+# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md031.md
+MD031: true
+
+# MD032/blanks-around-lists : Lists should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md032.md
+MD032: true
+
+# MD034/no-bare-urls : Bare URL used : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md034.md
+MD034: true
+
+# MD035/hr-style : Horizontal rule style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md035.md
+MD035: true
+
+# MD036/no-emphasis-as-heading : Emphasis used instead of a heading : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md036.md
+MD036: true
+
+# MD037/no-space-in-emphasis : Spaces inside emphasis markers : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md037.md
+MD037: true
+
+# MD038/no-space-in-code : Spaces inside code span elements : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md038.md
+MD038: true
+
+# MD039/no-space-in-links : Spaces inside link text : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md039.md
+MD039: true
+
+# MD042/no-empty-links : No empty links : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md042.md
+MD042: true
+
+# MD045/no-alt-text : Images should have alternate text (alt text) : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md045.md
+MD045: true
+
+# MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md046.md
+MD046:
+  style: "fenced"
+
+# MD047/single-trailing-newline : Files should end with a single newline character : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md047.md
+MD047: true
+
+# MD048/code-fence-style : Code fence style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md048.md
+MD048:
+  style: "backtick"
+
+# MD049/emphasis-style : Emphasis style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md049.md
+MD049:
+  style: "asterisk"
+
+# MD050/strong-style : Strong style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md050.md
+MD050:
+  style: "consistent"
+
+# MD051/link-fragments : Link fragments should be valid : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md051.md
+MD051: true
+
+# MD053/link-image-reference-definitions : Link and image reference definitions should be needed : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md053.md
+MD053: true
+
+# MD054/link-image-style : Link and image style : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md054.md
+MD054: true
+
+# MD056/table-column-count : Table column count : https://github.com/DavidAnson/markdownlint/blob/v0.33.0/doc/md056.md
+MD056: true

docs/blogs.md

@@ -11,5 +11,4 @@
 | 2021-08-23 | [Shepherding your Cloud Native “cattle” with Tornjak](https://medium.com/universal-workload-identity/shepherding-your-cloud-native-cattle-with-tornjak-eb0b9a7c96bc) | Introduction to Tornjak |
 | 2021-08-26 | [Open source workload identity management could help secure hybrid clouds](https://research.ibm.com/blog/tornjak-project-cncf) | IBM donates Tornjak to CNCF |
 
-
 [Tornjak Channel on Medium](https://medium.com/universal-workload-identity)

docs/config-tornjak-server.md

@@ -3,6 +3,7 @@
 This document is a reference for the Tornjak server, and it follows the [SPIRE server config](https://github.com/spiffe/spire/blob/main/doc/spire_server.md). It includes information about plugin types, built-in plugins, the server configuration file, plugin configuration, and command line options for `tornjak-agent` commands.
 
 ## Contents
+
 - [Command line options](#command-line-options)
 - [The Tornjak Config](#the-tornjak-config)
 - [General Tornjak Server Configs](#general-tornjak-server-configs)
@@ -20,20 +21,22 @@ The following flags are available for all tornjak-agent commands:
 | `--tornjak-config`     | Config file path for Tornjak agent |         | true     |
 | `--expandEnv`          | If flag included, expand environment variables in Tornjak config | false   | false    |
 
-Note these flags are passed in directly through the Tornjak container. 
+Note these flags are passed in directly through the Tornjak container.
 
 ### `tornjak-backend serverinfo`
-Prints the SPIRE config and Tornjak config given. 
+
+Prints the SPIRE config and Tornjak config given.
 
 ### `tornjak-backend http`
 
-Runs the tornjak server. 
+Runs the tornjak server.
 
 ## The Tornjak Config
 
-The Tornjak config that is passed in must follow a specific format. Examples of this format can be found [below](#sample-configuration-files). In general, it is split into the `server` section with [general Tornjak server configs](#general-tornjak-server-configs), and the `plugins` section. 
+The Tornjak config that is passed in must follow a specific format. Examples of this format can be found [below](#sample-configuration-files). In general, it is split into the `server` section with [general Tornjak server configs](#general-tornjak-server-configs), and the `plugins` section.
 
 ## General Tornjak Server Configs
+
 The server config will contain information for the two potential connections: HTTP and HTTPS. HTTPS can be configured to follow TLS or mTLS protocol. See below for sample configuration:
 
 ```hcl
@@ -42,7 +45,7 @@ server {
     spire_socket_path = "unix:///tmp/spire-server/private/api.sock" # socket to communicate with SPIRE server
 
     http { # required block
-	    port = 10000 # if HTTP enabled, opens HTTP listen port at container port 10000
+     port = 10000 # if HTTP enabled, opens HTTP listen port at container port 10000
     }
 
     https { # optional, recommended block
@@ -55,11 +58,11 @@ server {
 }
 ```
 
-We have two connection types that are opened by the server simultaneously: HTTP and HTTPS. HTTP is always operational.  The optional HTTPS connection is recommended for production use case.  When HTTPS is configured, the HTTP connection will redirect to the HTTPS (port and service). 
+We have two connection types that are opened by the server simultaneously: HTTP and HTTPS. HTTP is always operational.  The optional HTTPS connection is recommended for production use case.  When HTTPS is configured, the HTTP connection will redirect to the HTTPS (port and service).
 
-Under the HTTPS block, the fields `port`, `cert`, and `key` are required to enable TLS connection.  To enable the mutual TLS (mTLS), you must additionally include the `client_ca` field, so the verification can be done bi-directionally. 
+Under the HTTPS block, the fields `port`, `cert`, and `key` are required to enable TLS connection.  To enable the mutual TLS (mTLS), you must additionally include the `client_ca` field, so the verification can be done bi-directionally.
 
-For examples on enabling TLS and mTLS connections, please see [our TLS and mTLS documentation](../sample-keys/README.md). 
+For examples on enabling TLS and mTLS connections, please see [our TLS and mTLS documentation](../sample-keys/README.md).
 
 ## About Tornjak plugins
 
@@ -79,7 +82,7 @@ Tornjak supports several different plugin types, each representing a different f
 
 | Type | Name | Description |
 | ---- | ---- | ----------- |
-| DataStore     | [sql]() | Default SQL storage for Tornjak metadata |
+| DataStore     | SQL | Default SQL storage for Tornjak metadata |
 | Authenticator | [keycloak](/docs/plugin_server_authentication_keycloak.md) | Perform OIDC Discovery and extract roles from `realmAccess.roles` field |
 | Authorizer    | [RBAC](/docs/plugin_server_authorization_rbac.md) | Check api permission based on user role and defined authorization logic |
 
@@ -111,6 +114,5 @@ We have an extended configuration file with comments on each section found [here
 
 ## Further reading
 
-* [Tornjak Agent Architecture Overview](https://github.com/spiffe/tornjak/blob/main/docs/tornjak-agent.md)
-* [Tornjak API Documentation](https://github.com/spiffe/tornjak/blob/main/docs/tornjak-ui-api-documentation.md)
-
+- [Tornjak Agent Architecture Overview](https://github.com/spiffe/tornjak/blob/main/docs/tornjak-agent.md)
+- [Tornjak API Documentation](https://github.com/spiffe/tornjak/blob/main/docs/tornjak-ui-api-documentation.md)

docs/newEntry-json-format.md

@@ -1,3 +1,5 @@
+## JSON Format for New Entry
+
 ```json
 {
   "entries": [
@@ -38,4 +40,4 @@
     }
   ]
 }
-```
+```