Merge pull request #30 from rackerlabs/markdownlint

ci: add markdownlint for the docs

.github/workflows/mkdocs.yaml

@@ -25,9 +25,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+      - name: markdownlint
+        uses: nosborn/[email protected]
+        with:
+          files: docs
+          config_file: .markdownlint.yml
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
       - run: pip install -r requirements-docs.txt
       - run: mkdocs build
       - uses: actions/upload-pages-artifact@v2
@@ -39,7 +46,7 @@ jobs:
     needs: build
 
     # ensure we only run on commits to the main branch
-    if: github.ref == 'refs/heads/main'
+    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
 
     runs-on: ubuntu-latest
 

.markdownlint.yml

@@ -0,0 +1,37 @@
+---
+# Enable default rules
+default: true
+
+# MD007 - Unordered list indentation
+# Sets nested list indents to 4 spaces instead of the default of 2.
+# Required by Python-Markdown used by mkdocs
+MD007:
+    indent: 4
+
+# MD010 - No hard tabs
+# No hard tabs allowed in docs. Use 4 spaces instead.
+# This is disabled inline when used.
+MD010: true
+
+# MD013 - Line length
+# Defaults to 80 characters.
+MD013: false
+
+# MD014 - Dollar signs used before commands without showing output
+# Ignores terminal examples using dollar signs without any output examples after.
+# These occur in multiple places throughout our docs.
+MD014: false
+
+# MD024 - Multiple headings with the same content
+# Multiple identical headings in the document are not allowed
+# This is disabled on all of the release notes pages in docs/release-notes
+MD024: true
+
+# MD033 - Inline HTML
+# Triggered when raw HTML is used in a markdown document
+# Disabled inline when used.
+MD033: true
+
+# MD041 - First line in a file should be a top-level heading
+# This requires a top-level heading as the first line in every doc.
+MD041: true

docs/install-understack-ubuntu-k3s.md

@@ -11,13 +11,15 @@ git clone https://github.com/rackerlabs/understack.git
 ## Install Pre-requisites
 
 Install some packages we'll need later and some useful troubleshooting utilities.
+
 ```bash
 apt-get -y install curl jq net-tools telnet git apt-transport-https wget
 ```
 
 ## Update Ubuntu
 
 Update to the latest ubuntu packages and reboot if necessary.
+
 ```bash
 apt-get -y update
 ```
@@ -90,13 +92,15 @@ K3s installer should give us a working kubernetes.
 The kubectl config from k3s is in `/etc/rancher/k3s/k3s.yaml` and kubectl will automatically use it.
 
 See everything running in the new k3s kubernetes cluster:
+
 ```bash
 kubectl get all --all-namespaces
 ```
 
 ## Install UnderStack
 
 Get the repo:
+
 ```bash
 git clone https://github.com/rackerlabs/understack.git
 ```
@@ -108,6 +112,7 @@ References:
 ### Bootstrap UnderStack
 
 Run the initial bootstrap:
+
 ```bash
 kubectl kustomize --enable-helm bootstrap | kubectl apply --server-side -f -
 ```
@@ -331,6 +336,7 @@ Load the secrets values file from the cluster:
 ```
 
 Label the kubernetes nodes as being openstack enabled:
+
 ```bash
 kubectl label node $(kubectl get nodes -o 'jsonpath={.items[*].metadata.name}') openstack-control-plane=enabled
 ```
@@ -399,7 +405,7 @@ kubectl exec -it openstack-admin-client -n openstack -- openstack baremetal cond
 
 If everything is working, you should see output similar to the following:
 
-```
+```bash
 # kubectl exec -it openstack-admin-client -n openstack -- openstack baremetal conductor list
 +---------------------------------------------+-----------------+-------+
 | Hostname                                    | Conductor Group | Alive |