Markdownlint is a popular Node.js style checker and lint tool for Markdown/CommonMark files. It helps ensure consistency and adherence to standards in Markdown files by providing a set of rules. In this guide, we’ll explain why Markdownlint is used in the OpenTelemetry.io project and demonstrate how to implement it.
Why Use Markdownlint in OpenTelemetry.io?
OpenTelemetry.io is an open-source project that provides a collection of tools, APIs, and SDKs for generating, collecting, and exporting telemetry data. Markdown is used extensively in the project for documentation, and its flexibility can sometimes lead to inconsistent formatting. Markdownlint is used to address these issues by providing a set of rules to ensure that Markdown files adhere to a consistent style.
Installing Markdownlint
To use Markdownlint in the OpenTelemetry.io project, first, install it as a development dependency:
npm install markdownlint --save-dev
Markdownlint is used by over 120 other projects in the npm registry. You can find more information about Markdownlint on its npm page and its GitHub repository.
Using Markdownlint in OpenTelemetry.io
Markdownlint can be used in various ways, such as through its command-line interface, extensions for popular editors, or as part of a build system. In the OpenTelemetry.io project, Markdownlint is used as part of the continuous integration (CI) pipeline to check the Markdown files for any issues before merging the pull requests.
CI Configuration
The following is an example of how Markdownlint is configured in the OpenTelemetry.io CI pipeline using GitHub Actions:
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup Node.js
uses: actions/setup-node@v1
with:
node-version: 14.x
- name: Install dependencies
run: npm install
- name: Check Markdown files
run: npm run lint:md
This configuration sets up the CI pipeline to run Markdownlint whenever there is a push or pull request. The lint:md script is defined in the package.json file as follows:
"scripts": {
"lint:md": "markdownlint ./**/*.md"
}
Markdownlint Rules
Markdownlint comes with a set of rules that can be customized to fit the project’s needs. The following rules are used in the OpenTelemetry.io project:
MD018: No space after hash on atx style headingsMD022: Headings should be surrounded by blank linesMD023: Headings must start at the beginning of the line
These rules help ensure that the Markdown files have a consistent formatting style.
Conclusion
Markdownlint is an essential tool for maintaining consistency and adherence to standards in Markdown files in the OpenTelemetry.io project. By integrating it into the CI pipeline, the project can ensure that any Markdown files added or modified adhere to the project’s style guidelines. For more information on Markdownlint, including its rules and configuration options, refer to the Markdownlint documentation.
