Merge pull request #218 from nathan-weinberg/md-lint

ci: add markdown linter

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+
+name: Lint Markdown documents
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - '**/*.md'
+      - '.markdownlint-cli2.yaml'
+      - '.github/workflows/docs.yml' # This workflow
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - '**/*.md'
+      - '.markdownlint-cli2.yaml'
+      - '.github/workflows/docs.yml' # This workflow
+
+env:
+  LC_ALL: en_US.UTF-8
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Harden Runner"
+        uses: step-security/harden-runner@a4aa98b93cab29d9b1101a6143fb8bce00e2eac4 # v2.7.1
+        with:
+          egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
+      - name: "Checkout"
+        uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4
+        with:
+          fetch-depth: 0
+      - name: "Check Markdown documents"
+        uses: DavidAnson/markdownlint-cli2-action@b4c9feab76d8025d1e83c653fa3990936df0e6c8 # v16.0.0
+        with:
+          globs: '**/*.md'

.markdownlint-cli2.yaml

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: Apache-2.0
+
+config:
+  line-length: false
+  no-emphasis-as-header: false
+  first-line-heading: false
+  code-block-style: false
+  no-duplicate-header: false
+  single-trailing-newline: false
+globs:
+  - "**/*.md"
+ignores:
+  - ".github/**"
+  - ".tox/**"
+  - "venv/**"
+  - ".venv/**"

COCC.md

@@ -1,14 +1,14 @@
 # Filing a Code of Conduct Violation Report
 
-We take reports of violations to our project [Code of Conduct](https://github.com/instructlab/community/blob/main/CODE_OF_CONDUCT.md) with the utmost seriousness and will act upon them as quickly as possible. 
+We take reports of violations to our project [Code of Conduct](https://github.com/instructlab/community/blob/main/CODE_OF_CONDUCT.md) with the utmost seriousness and will act upon them as quickly as possible.
 
 To report a Code of Conduct violation to our Code of Conduct Committee, you may reach out to us by email at [coc@instructlab.ai](mailto:coc@instructlab.ai). The email will be read and acted upon by our Code of Conduct Committee members.
 
 If you experience a Code of Conduct violation in our InstructLab Slack workspace, please follow the [instructions in our moderation guide](https://github.com/instructlab/community/blob/main/InstructLabSlackModerationGuide.md#reporting-abuse) to get immediate help in Slack.
 
-As part of our follow up on your report, we would like to contact you for further discussion. If you would prefer not to engage beyond reporting the matter to the committee, please let us know that as part of your submission. We will respect your request. 
+As part of our follow up on your report, we would like to contact you for further discussion. If you would prefer not to engage beyond reporting the matter to the committee, please let us know that as part of your submission. We will respect your request.
 
-# Code of Conduct Committee Members
+## Code of Conduct Committee Members
 
 The current members of the CoCC are:
 

CODE_OF_CONDUCT.md

@@ -69,9 +69,9 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>

CONTRIBUTING.md

@@ -50,30 +50,30 @@ We welcome contributions in the form of pull requests for documentation. To subm
 The InstructLab project uses the _Fork and Pull_ model for contribution that is common in many open source repositories; this entails multiple steps, including forking and cloning the repository, creating a _pull request_, or PR, and more. For details on this process, check out [The GitHub Workflow
 Guide](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md) from Kubernetes.
 
-After you have forked and cloned the repository, you can start the contribution process by looking at the issue trackers of the [community repository](https://github.com/instructlab/community/pulls), [CLI repository](https://github.com/instructlab/instructlab/issues), or the [taxonomy repository](https://github.com/instructlab/taxonomy/issues). You can then pick up an issue by leaving a comment on said issue, and address the issue in a pull request (PR). Prior to submission, make sure that your changes pass formatting, linting, and unit tests. Additionally, all PRs must agree to the terms of [Developer Certificate of Origin (DCO)](https://developercertificate.org/) by signing off your commits. Only PRs with commits signed off are accepted. If you didn't sign off your commits before creating the pull request, no worries, you can fix that after the fact. For more information about this process, see [Developer Certificate of Origin (DCO)](#DCO).
+After you have forked and cloned the repository, you can start the contribution process by looking at the issue trackers of the [community repository](https://github.com/instructlab/community/pulls), [CLI repository](https://github.com/instructlab/instructlab/issues), or the [taxonomy repository](https://github.com/instructlab/taxonomy/issues). You can then pick up an issue by leaving a comment on said issue, and address the issue in a pull request (PR). Prior to submission, make sure that your changes pass formatting, linting, and unit tests. Additionally, all PRs must agree to the terms of [Developer Certificate of Origin (DCO)](https://developercertificate.org/) by signing off your commits. Only PRs with commits signed off are accepted. If you didn't sign off your commits before creating the pull request, no worries, you can fix that after the fact. For more information about this process, see [Developer Certificate of Origin (DCO)](#developer-certificate-of-origin-dco).
 
 Then, you can submit the PR to be reviewed. In general, we follow the standard [GitHub pull request](https://help.github.com/en/articles/about-pull-requests) process. Follow the provided template on your PR to include details about your pull request for the maintainers.
 
-> [!IMPORTANT] 
+> [!IMPORTANT]
 > If you are seeking to make a larger contribution, such as introducing a new feature or functionality, or refactoring a significant portion of the codebase to improve performance, readability, or maintainability, [get in touch](#communication) with us prior to starting. This helps ensure that your time is not wasted working on a change that the project developers will not accept into the codebase.
 
 ### Pull request review
 
 Once you've created a pull request (PR), maintainers will review your code and may make suggestions to fix before merging. It will be easier for your PR to receive reviews if you consider the criteria the reviewers follow while working. Remember to:
 
-- Run tests locally and ensure that they pass
-- Follow the project coding conventions
-- Write detailed commit messages
-- Break large changes into a logical series of smaller patches, which are easy to understand individually and combine to solve a broader issue
+* Run tests locally and ensure that they pass
+* Follow the project coding conventions
+* Write detailed commit messages
+* Break large changes into a logical series of smaller patches, which are easy to understand individually and combine to solve a broader issue
 
 For a list of the maintainers and triagers, see the [MAINTAINERS.md](MAINTAINERS.md) page.
 
 ### Proposing new features
 
 To propose a new feature, it's best to raise an issue in the appropriate repository:
 
-- [Instructlab CLI repository](https://github.com/instructlab/instructlab/issues)
-- [Taxonomy repository](https://github.com/instructlab/taxonomy/issues)
+* [Instructlab CLI repository](https://github.com/instructlab/instructlab/issues)
+* [Taxonomy repository](https://github.com/instructlab/taxonomy/issues)
 
 This way, features can be discussed with the project maintainers, ensuring that your time is not wasted working on a feature that the project developers will not accept into the codebase.
 
@@ -108,20 +108,20 @@ git commit -s
 
 The following example includes a `Signed-off-by:` line, which indicates that the submitter has accepted the DCO:
 
-```
+```text
 Signed-off-by: John Doe <john.doe@example.com>
 ```
 
 We automatically verify that all commit messages contain a `Signed-off-by:` line with your email address.
 
-#### Useful tools for doing DCO signoffs <DCO id="DCO resources"></DCO>
+#### Useful tools for doing DCO signoffs
 
 There are a number of tools that make it easier for developers to manage DCO signoffs.
 
-- DCO command line tool, which let's you do a single signoff for an entire repo ( <https://github.com/coderanger/dco> )
-- GitHub UI integrations for adding the signoff automatically ( <https://github.com/scottrigby/dco-gh-ui> )
-- Chrome - <https://chrome.google.com/webstore/detail/dco-github-ui/onhgmjhnaeipfgacbglaphlmllkpoijo>
-- Firefox - <https://addons.mozilla.org/en-US/firefox/addon/scott-rigby/?src=search>
+* DCO command line tool, which let's you do a single signoff for an entire repo ( <https://github.com/coderanger/dco> )
+* GitHub UI integrations for adding the signoff automatically ( <https://github.com/scottrigby/dco-gh-ui> )
+* Chrome - <https://chrome.google.com/webstore/detail/dco-github-ui/onhgmjhnaeipfgacbglaphlmllkpoijo>
+* Firefox - <https://addons.mozilla.org/en-US/firefox/addon/scott-rigby/?src=search>
 
 ## Communication
 
@@ -133,12 +133,12 @@ The following resources include additional information about each repository, su
 
 ### ilab CLI tool additional resources
 
-- [`ilab` CLI tool README.md](https://github.com/instructlab/instructlab/blob/main/README.md#). This resources provides information about the `ilab` CLI tool, including an overview, getting started, training the model, submitting a pull request, etc.
+* [`ilab` CLI tool README.md](https://github.com/instructlab/instructlab/blob/main/README.md#). This resources provides information about the `ilab` CLI tool, including an overview, getting started, training the model, submitting a pull request, etc.
 
-- [`ilab` CLI tool CONTRIBUTING.md](https://github.com/instructlab/instructlab/blob/main/CONTRIBUTING/CONTRIBUTING.md). This resources provides information about contributing to the `ilab` CLI tool repository, reporting bugs, testing, coding styles, etc.
+* [`ilab` CLI tool CONTRIBUTING.md](https://github.com/instructlab/instructlab/blob/main/CONTRIBUTING/CONTRIBUTING.md). This resources provides information about contributing to the `ilab` CLI tool repository, reporting bugs, testing, coding styles, etc.
 
 ### Taxonomy additional resources
 
-- [Taxonomy README.md](https://github.com/instructlab/taxonomy/blob/main/README.md). This resource provides information about the taxonomy repository, including getting started, YAML examples for skills and knowledge pull requests, how to contribute, etc.
+* [Taxonomy README.md](https://github.com/instructlab/taxonomy/blob/main/README.md). This resource provides information about the taxonomy repository, including getting started, YAML examples for skills and knowledge pull requests, how to contribute, etc.
 
-- [Taxonomy CONTRIBUTING.md](https://github.com/instructlab/taxonomy/blob/main/CONTRIBUTING.md). This resource contains information and best practices for contributing to the taxonomy repository.
+* [Taxonomy CONTRIBUTING.md](https://github.com/instructlab/taxonomy/blob/main/CONTRIBUTING.md). This resource contains information and best practices for contributing to the taxonomy repository.