I’ll confess, reader. My markdown formatting was messy. I don’t like messy, so I decided to fix it and automate it.
The solution involves:
- The great markdownlint tool
- A VS Code Extension that gives me linting within the IDE
- A rules file to allow for some exceptions in cases where I truly need them
- A GitHub Action to run as part of my pull requests, to keep me honest.
Installing the Markdownlint Extension
In the extensions window, search for
markdownlint and install it (extension ID:
Now, you’ll start getting feedback on what needs fixing when you have a file open. It’s really helpful.
Create a Rules File
- Add a
.markdownrcfile to the root of your repository to capture rules. You can turn off various rules as things fail if you need to. My example rules file can be found here
Run As Part of a Build
We’ll utilize GitHub actions for this.
- Create a GitHub Action workflow by creating a file in your repo at
.githubis a folder in this case.)
Add the following, changing the values as they suit you:
name: Housekeeping on: push: branches: - main # Modify if you use a different main branch name, such as the legacy "master" name. pull_request: branches: - main # Modify if you use a different main branch name, such as the legacy "master" name. jobs: linting: name: "Markdown linting" runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 name: Check out the code - name: Lint Code Base uses: docker://avtodev/markdown-lint:v1 with: args: "**/*.md"
What’s is this GitHub Action file doing?
- It runs on any main branch commit or any PR against my main branch
- It runs the GitHub action on an Ubuntu instance
- It checks out all my code for the blog, which includes all the markdown files
- It pulls a Docker container that is published to Docker Hub, which has been set up by someone else to run markdownlint (thanks, people who care about OSS!)
- It passes in the argument to the container of which files to run within Markdown lint
- When it runs, it automatically sees and respects the
.markdownlintrcrules file, keeping it consistent with my local environment.
Once I committed this file to a PR, I saw the linting begin.
Wash, Rinse, Repeat
The first time I enabled this with a PR, I got a lot of failures, as one might expect. I kept making small commits over time and eventually I got there.
Now, I get local linting support within VS Code and build time support via GitHub Actions. For free! 1.
By free, I mean thanks to someone else’s very hard work that they are often under-compensated and under-supported for. Go look into contributing to open source projects, or consider donating to an author or group that has enabled you to work better. ↩