diff --git a/.github/.markdownlint.yml b/.github/.markdownlint.yml
new file mode 100644
index 0000000..b25be39
--- /dev/null
+++ b/.github/.markdownlint.yml
@@ -0,0 +1,30 @@
+# See rules documentation: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+
+# Default state for all rules
+default: true
+
+# ul-style # default: consistent
+MD004: consistent
+
+# hard-tabs
+MD010: false
+
+# line-length
+MD013: false
+
+# no-duplicate-header
+MD024:
+  siblings_only: true
+
+#single-title
+MD025: true
+
+# ol-prefix
+MD029:
+  style: one_or_ordered
+
+# no-inline-html
+MD033: false
+
+# fenced-code-language
+MD040: false
diff --git a/.github/workflows/TODO.md b/.github/workflows/TODO.md
new file mode 100644
index 0000000..dbb1eed
--- /dev/null
+++ b/.github/workflows/TODO.md
@@ -0,0 +1,14 @@
+Evaluate:
+
+* markdownlint
+  * assessment: go
+  * used by opentelemetry/opentelemetry-go
+  * packaged as github action
+* misspell
+* spellcheck
+* govulncheck
+* [x] godoc-lint:
+  * assessment: no go
+  * too simplistic: no real value added
+  * not integrated into golangci's suite of linters
+  * no packaged github action
diff --git a/.github/workflows/markdown.yml b/.github/workflows/markdown.yml
new file mode 100644
index 0000000..9ca7938
--- /dev/null
+++ b/.github/workflows/markdown.yml
@@ -0,0 +1,153 @@
+name: Markdown
+
+on:
+  pull_request_target:
+    paths:
+    - '**/*.md'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+env:
+  comment-title: Markdown linter
+
+jobs:
+  markdown-changed:
+    runs-on: ubuntu-latest
+    outputs:
+      proceed: ${{ steps.changed-markdown-files.outputs.any_changed }}
+      all_changed_files: ${{ steps.changed-markdown-files.outputs.all_changed_files }}
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+        #ref: "refs/pull/${{ github.event.number }}/merge"  # it's okay to pull the user's changes: we just scan md's
+
+    - name: Get changed markdown files
+      id: changed-markdown-files
+      uses: tj-actions/changed-files@v45
+      with:
+        files: '**/*.md'
+
+    - name: Notify
+      run: |
+        echo "::notice::Detected some changed markdown files"
+        echo "${{ steps.changed-markdown-files.outputs.all_changed_files }}"
+
+  lint-markdown:
+    needs: markdown-changed
+    if: needs.markdown-changed.outputs.proceed == 'true'
+    runs-on: ubuntu-latest
+    env:
+      lintreport: './markdownlint-report.txt'
+    outputs:
+      proceed: ${{ steps.report-exists.outputs.proceed }}
+      report: ${{ steps.report-exists.outputs.report }}
+
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
+        #ref: "refs/pull/${{ github.event.number }}/merge"  # it's okay to pull the user's changes: we just scan md's
+
+    - name: Run markdown linter
+      continue-on-error: true
+      id: markdownlint
+      uses: docker://avtodev/markdown-lint:v1.5
+      with:
+        config: ./.github/.markdownlint.yml
+        args: '${{ needs.markdown-changed.outputs.all_changed_files }}'
+        output: '${{ env.lintreport }}'
+
+    - name: Find previous PR comment
+      if: steps.markdownlint.outcome == 'success'
+      uses: peter-evans/find-comment@v3
+      id: findcomment
+      with:
+        issue-number:  ${{ github.event.pull_request.number }}
+        body-includes: ${{ env.comment-title }}
+        direction: last
+
+    - name: Comment on success
+      if: steps.markdownlint.outcome == 'success'
+      id: congrats
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-id: ${{ steps.findcomment.outputs.comment-id }}
+        reactions: hooray
+        reactions-edit-mode: replace
+        body: |
+          ### ${{ env.comment-title }}
+          Markdown looks good to me. Congrats!
+
+    - name: Check lint report exists
+      if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) != '' }}
+      id: report-exists
+      run: |
+        echo 'report<<EOF' >> $GITHUB_OUTPUT
+        cat ${{ env.lintreport }}|sed -e '$a\' >> $GITHUB_OUTPUT
+        echo 'EOF' >> $GITHUB_OUTPUT
+
+        if [[ "$(cat ${{ env.lintreport }}|wc -l)" != "0" ]] ; then
+          echo "proceed=true" >> $GITHUB_OUTPUT
+          echo "::notice::Detected some linting issues with changed markdown"
+          cat ${{ env.lintreport }}|sed -e '$a\'
+        else
+          echo "proceed=false" >> $GITHUB_OUTPUT
+          echo "::notice::No linting issues with changed markdown"
+        fi
+
+    - name: Other linter errors
+      if: ${{ steps.markdownlint.outcome != 'success' && hashFiles(env.lintreport) == '' }}
+      run: |
+        echo "::error::markdown linter encountered an error"
+        exit 1
+
+  pr-comment:
+    needs: lint-markdown
+    if: needs.lint-markdown.outputs.proceed == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Format PR comment
+      id: commentformatter
+      uses: skills/action-text-variables@v1
+      with:
+        template-vars: |
+            text='${{ needs.lint-markdown.outputs.report }}'
+        template-text: |
+            ### ${{ env.comment-title }}
+            Some markdown linting issues were detected in modified .md files.
+
+            This check is advisory only and not blocking. Please adopt a nice markdown style.
+
+            Markdown formatting rules are documented [here](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md).
+            <br> 
+            {{ text }}
+
+    - name: Find previous PR comment
+      uses: peter-evans/find-comment@v3
+      id: findcomment
+      with:
+        issue-number:  ${{ github.event.pull_request.number }}
+        body-includes: ${{ env.comment-title }}
+        direction: last
+
+    - name: Create or update PR comment
+      uses: peter-evans/create-or-update-comment@v4
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-id: ${{ steps.findcomment.outputs.comment-id }}
+        reactions: confused
+        reactions-edit-mode: replace
+        body: ${{ steps.commentformatter.outputs.updated-text }}
+        edit-mode: replace
+
+    - name: Notify
+      run: |
+        echo "::notice::Commented pull request ${{ github.event.pull_request.number }}"
+        echo "::debug::${{ steps.commentformatter.outputs.updated-text }}"
diff --git a/doc.md b/doc.md
new file mode 100644
index 0000000..850654e
--- /dev/null
+++ b/doc.md
@@ -0,0 +1,24 @@
+# blag blah
+# blag blah
+
+Ordered list:
+
+ 1. xyz     
+ 2. abc     
+ 
+First list:
+
+ - a
+ - b
+ - c
+ 
+Second list:
+
+ * A
+ * B
+ * C
+
+Another Ordered list:
+
+ 0. xyz     
+ 0. abc     
diff --git a/html.md b/html.md
new file mode 100644
index 0000000..431ff74
--- /dev/null
+++ b/html.md
@@ -0,0 +1,6 @@
+<h1>dfkjfkfj<h1>
+
+
+ERGGLGKLK
+==========
+this is a title