Add Markdown Linting (#726)

* feat: add markdownlint with most rules disabled to pass checks
* style: enable initial markdownlint rules; enables all rules that do not currently trigger any warnings or issues
* build: enable markdownlint in github actions
* style: enable ul-style rule to test ci
* fix: change linting glob to check nested *.md files
* style: use consistent unordered list marker
* style(markdown): enforce no-trailing-spaces - There should be 0 or 2 trailing spaces.
* style(markdown): enforce no-hard-tabs
* style(markdown): enforce no-multiple-blanks
* style(markdown): enforce commands-show-output
* style(markdown): enforce blanks-around-headings
* style(markdown): enable no-inline-html with allowed elements
* style(markdown): enforce no-bare-urls
* style(markdown): enforce fenced-code-language
* style(markdown): enforce first-line-heading
* style(markdown): enforce code-block-style
* style(markdown): enforce link-image-reference-definitions
  - fixes a broken link in the graphql guides
  - fixes a duplicate url reference in the Git guides
* style(markdown): enforce no-trailing-punctuation; also removes an extraneous url reference
* style(markdown): enable no-duplicate-heading with siblings only option
* feat: add lefthook and pre-commit hook for markdownlint
* chore: update markdownlint config file
* ci: lint only on pull request
* config: add .tool-versions file

Author: vburzynski

.github/workflows/linting.yml

@@ -0,0 +1,11 @@
+on: [pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: DavidAnson/markdownlint-cli2-action@v19
+      with:
+        globs: |
+          ./**/*.md

.github/workflows/main.yml

@@ -1,6 +1,6 @@
 name: update-templates
 
-on: 
+on:
   push:
     branches:
       - main

.gitignore

@@ -0,0 +1,3 @@
+.obsidian
+
+node_modules

.markdownlint-cli2.jsonc

@@ -0,0 +1,161 @@
+{
+  // https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#rules--aliases
+  // https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-jsonc-example/.markdownlint-cli2.jsonc
+  // https://github.com/DavidAnson/markdownlint-cli2/blob/main/schema/markdownlint-config-schema.json
+  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2/refs/heads/main/schema/markdownlint-cli2-config-schema.json",
+  "gitignore": true,
+  "config": {
+    /* MD001 - Heading levels should only increment by one level at a time */
+    "heading-increment": true,
+
+    /* MD003 - Heading style */
+    "heading-style": true,
+
+    /* MD004 - Unordered list style */
+    "ul-style": true,
+
+    /* MD005 - Inconsistent indentation for list items at the same level */
+    "list-indent": true,
+
+    /* MD007 - Unordered list indentation */
+    "ul-indent": true,
+    // { "indent": 2, "start_indented": false },
+
+    /* MD009 - Trailing spaces */
+    "no-trailing-spaces": true,
+
+    /* MD010 - Hard tabs */
+    "no-hard-tabs": true,
+
+    /* MD011 - Reversed link syntax */
+    "no-reversed-links": true,
+
+    /* MD012 - Multiple consecutive blank lines */
+    "no-multiple-blanks": true,
+
+    /* MD013 - Line length */
+    // NOTE: Disabled to allow lines of any length; could be enabled in a separate PR after discussion
+    "line-length": false,
+
+    /* MD014 - Dollar signs used before commands without showing output */
+    "commands-show-output": true,
+
+    /* MD018 - No space after hash on atx style heading */
+    "no-missing-space-atx": true,
+
+
+    /* MD019 - Multiple spaces after hash on atx style heading */
+    "no-multiple-space-atx": true,
+
+    /* MD020 - No space inside hashes on closed atx style heading */
+    "no-missing-space-closed-atx": true,
+
+    /* MD021 - Multiple spaces inside hashes on closed atx style heading */
+    "no-multiple-space-closed-atx": true,
+
+    /* MD022 - Headings should be surrounded by blank lines */
+    "blanks-around-headings": true,
+
+    /* MD023 - Headings must start at the beginning of the line */
+    "heading-start-left": true,
+
+    /* MD024 - Multiple headings with the same content */
+    "no-duplicate-heading": {
+      "siblings_only": true
+    },
+
+    /* MD025 - Multiple top-level headings in the same document */
+    "single-title": true,
+
+    /* MD026 - Trailing punctuation in heading */
+    "no-trailing-punctuation": true,
+
+    /* MD027 - Multiple spaces after blockquote symbol */
+    "no-multiple-space-blockquote": true,
+
+    /* MD028 - Blank line inside blockquote */
+    "no-blanks-blockquote": true,
+
+    /* MD029 - Ordered list item prefix */
+    "ol-prefix": true,
+
+    /* MD030 - Spaces after list markers */
+    "list-marker-space": true,
+
+    /* MD031 - Fenced code blocks should be surrounded by blank lines */
+    "blanks-around-fences": true,
+
+    /* MD032 - Lists should be surrounded by blank lines */
+    "blanks-around-lists": true,
+
+    /* MD033 - Inline HTML */
+    "no-inline-html": {
+      "allowed_elements": ["dl", "dt", "dd", "kbd", "details"]
+    },
+
+    /* MD034 - Bare URL used */
+    "no-bare-urls": true,
+
+    /* MD035 - Horizontal rule style */
+    "hr-style": true,
+
+    /* MD036 - Emphasis used instead of a heading */
+    "no-emphasis-as-heading": true,
+
+    /* MD037 - Spaces inside emphasis markers */
+    "no-space-in-emphasis": true,
+
+    /* MD038 - Spaces inside code span elements */
+    "no-space-in-code": true,
+
+    /* MD039 - Spaces inside link text */
+    "no-space-in-links": true,
+
+    /* MD040 - Fenced code blocks should have a language specified */
+    "fenced-code-language": true,
+
+    /* MD041 - First line in a file should be a top-level heading */
+    "first-line-heading": true,
+
+    /* MD042 - No empty links */
+    "no-empty-links": true,
+
+    /* MD043 - Required heading structure */
+    "required-headings": true,
+
+    /* MD044 - Proper names should have the correct capitalization */
+    "proper-names": true,
+
+    /* MD045 - Images should have alternate text (alt text) */
+    "no-alt-text": true,
+
+    /* MD046 - Code block style */
+    "code-block-style": true,
+
+    /* MD047 - Files should end with a single newline character */
+    "single-trailing-newline": true,
+
+    /* MD048 - Code fence style */
+    "code-fence-style": true,
+
+    /* MD049 - Emphasis style */
+    "emphasis-style": true,
+
+    /* MD050 - Strong style */
+    "strong-style": true,
+
+    /* MD051 - Link fragments should be valid */
+    "link-fragments": true,
+
+    /* MD052 - Reference links and images should use a label that is defined */
+    "reference-links-images": {
+      "shortcut_syntax": true
+    },
+
+    /* MD053 - Link and image reference definitions should be needed */
+    "link-image-reference-definitions": true,
+
+    /* MD054 - Link and image style */
+    "link-image-style": true
+  }
+}

.tool-versions

@@ -0,0 +1 @@
+node latest

CONTRIBUTING.md

@@ -5,7 +5,7 @@ to abide by the [thoughtbot Code Of Conduct].
 
 We expect everyone to follow the code of conduct anywhere in thoughtbot's
 project codebases, issue trackers, chatrooms, mailing lists, meetups, at other events, and in-person.
-Violators will be warned by the core team. 
+Violators will be warned by the core team.
 Repeat violations will result in being blocked or banned by the core team at or before the 3rd violation.
 
 [thoughtbot code of conduct]: https://thoughtbot.com/open-source-code-of-conduct

README.md

@@ -114,5 +114,4 @@ We are [available for hire][hire].
 [community]: https://thoughtbot.com/community?utm_source=github
 [hire]: https://thoughtbot.com/hire-us?utm_source=github
 
-
 <!-- END /templates/footer.md -->

_template/README.md

@@ -16,7 +16,7 @@ This typically takes one of three forms:
 2. Primarily textual sections
 3. A combination of both
 
-## How to...
+## How To Guides
 
 This section, if applicable, should index a list of "How-to" guides for this
 guide's topic. These should be stored relative to this `README.md` file in a

_template/how-to/do-something-else.md

@@ -1,3 +1,3 @@
-## How to Do Something Else
+# How to Do Something Else
 
 This is an example how-to guide. Write anything you want here!

_template/how-to/do-something.md

@@ -1,3 +1,3 @@
-## How to Do Something
+# How to Do Something
 
 This is an example how-to guide. Write anything you want here!

code-review/README.md

@@ -69,7 +69,7 @@ Watch a presentation that covers this material from [Derek Prior at RailsConf 20
   - You may want to consider before/after screenshots or screencasts whenever applicable.
 
 - **Link to the code review from the ticket/story**
-  - "Ready for review: https://github.com/organization/project/pull/1"
+  - "Ready for review: `https://github.com/organization/project/pull/1`
 
 - **Push commits based on earlier rounds of feedback as isolated commits to the branch**
   - Do not squash until the branch is ready to merge.

data/README.md

@@ -24,6 +24,7 @@ A guide for managing a series of tubes.
   messages from different partitions to be processed out of order.
 
 ## Glossary
+
 <dl>
   <dt>Data Engineering</dt>
   <dd>
@@ -174,6 +175,6 @@ A guide for managing a series of tubes.
   <dt>Consumer</dt>
   <dd>An application or process that reads from a data stream.</dd>
 
-  <dt>Producer</dt> 
+  <dt>Producer</dt>
   <dd>An application or process that writes to a data stream.</dd>
-</dl>
+</dl>

git/README.md

@@ -54,12 +54,14 @@ git commit --verbose
 
 Write a [good commit message]. Example format:
 
-    Present-tense summary under 50 characters
+```text
+Present-tense summary under 50 characters
 
-    - More information about commit (under 72 characters).
-    - More information about commit (under 72 characters).
+- More information about commit (under 72 characters).
+- More information about commit (under 72 characters).
 
-    http://project.management-system.com/ticket/123
+http://project.management-system.com/ticket/123
+```
 
 If you've created more than one commit, [use `git rebase` interactively] to squash them into cohesive commits with good
 messages:
@@ -78,7 +80,6 @@ Submit a [GitHub pull request].
 
 Ask for a code review in the project's chat room.
 
-[good commit message]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 [use `git rebase` interactively]: https://help.github.com/articles/about-git-rebase/
 [github pull request]: https://help.github.com/articles/using-pull-requests/
 

graphql/README.md

@@ -65,3 +65,4 @@ be used.
 - Avoid returning null from operations. [#630]
 
 [graphql specification]: https://graphql.github.io/graphql-spec/
+[#630]: https://github.com/thoughtbot/guides/pull/630

javascript/README.md

@@ -27,19 +27,18 @@
 
 - Use [Prettier defaults](https://prettier.io/docs/en/options.html) with the following additional configuration (.prettierrc):
 
-	```json
-	{
-	  "singleQuote": true
-	}
-	```
+  ```json
+  {
+    "singleQuote": true
+  }
+  ```
 
   This configuration includes:
   - Use semicolons at the end of each statement ([sample](/javascript/sample.js#L5))
   - Prefer single quotes ([sample](/javascript/sample.js#L11))
-  - Use a trailing comma after each item in a multi-line array or object literal, including the last item. ([sample](/javascript/sample.js#L11)) 
- 
-If ESLint is used along with Prettier, the ESLInt plugin [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier) should also be used to turn off all ESLint style rules that are already handled by Prettier.
+  - Use a trailing comma after each item in a multi-line array or object literal, including the last item. ([sample](/javascript/sample.js#L11))
 
+If ESLint is used along with Prettier, the ESLInt plugin [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier) should also be used to turn off all ESLint style rules that are already handled by Prettier.
 
 [babel]: https://babeljs.io/
 [eslint]: https://eslint.org/

lefthook.yml

@@ -0,0 +1,52 @@
+# EXAMPLE USAGE:
+#
+#   Refer for explanation to following link:
+#   https://lefthook.dev/configuration/
+#
+# pre-push:
+#   jobs:
+#     - name: packages audit
+#       tags:
+#         - frontend
+#         - security
+#       run: yarn audit
+#
+#     - name: gems audit
+#       tags:
+#         - backend
+#         - security
+#       run: bundle audit
+#
+# pre-commit:
+#   parallel: true
+#   jobs:
+#     - run: yarn eslint {staged_files}
+#       glob: "*.{js,ts,jsx,tsx}"
+#
+#     - name: rubocop
+#       glob: "*.rb"
+#       exclude:
+#         - config/application.rb
+#         - config/routes.rb
+#       run: bundle exec rubocop --force-exclusion {all_files}
+#
+#     - name: govet
+#       files: git ls-files -m
+#       glob: "*.go"
+#       run: go vet {files}
+#
+#     - script: "hello.js"
+#       runner: node
+#
+#     - script: "hello.go"
+#       runner: go run
+pre-commit:
+  parallel: true
+  jobs:
+    - name: Lint Markdown
+      glob: "*.md"
+      group:
+        parallel: true
+        jobs:
+          - name: Markdownlint
+            run: npx markdownlint-cli2 {staged_files}

mise.toml

@@ -0,0 +1,2 @@
+[tools]
+node = "latest"