docs-lint

Content linting for Elastic documentation.

Install

npm install -g @elastic/docs-lint

Use

To lint docs files in the current directory use:

docs-lint [directory] [file type flag]

Note: If no flag is provided, it will default to --md.

Example: Lint AsciiDoc files

To lint AsciiDoc files use the --asciidoc flag.

For example, to lint just the map-related AsciiDoc files from inside the Kibana directory, use:

docs-lint docs/maps/ --asciidoc

Example: Lint MDX files

To lint MDX files use the --mdx flag.

For example, to lint the all MDX files in the integration docs:

docs-lint dist/ --mdx

Example: Lint Markdown files

To lint Markdown files use the --md flag.

For example, to lint the all the developer docs in your team's GitHub repository:

docs-lint docs/ --md

Rules

Natural language linting

Uses a combination of open source and custom retext plugins to lint for spelling and style guide compliance, including:

• retext-elastic-attributes: A custom plugin that checks for instances of strings attached to an attribute in attributes.asciidoc and prompts you to replace the string with the related attribute.
• retext-spell: An open source plugin that checks spelling. I used dictionary-en and have already started generating a list of words to add to the dictionary (for example, Elastic product names, industry terms, and third-party product names).
• retext-repeated-words: An open source plugin that checks for ~~for~~ repeated words, which can be quite elusive.
• More to come!

Rules by file type

| | AsciiDoc | MDX | Markdown | |---|---|---|---| | Check for shared attribute use(retext-elastic-attributes) | ✅ | 🔜 | ❌ | | Check spelling(retext-spell) | ✅ | 🔜 | ✅ | | Check for repeated words(retext-repeated-words) | ✅ | 🔜 | ✅ |

Syntax linting

MDX

• remark-mdx: An open source plugin that validates MDX syntax.
• remark-elastic-autolink: A custom plugin that creates links from standard URLs that are included in Markdown as plain text.
• remark-elastic-frontmatter: A custom plugin that checks that the frontmatter for a page is valid.
• remark-elastic-links: A custom plugin that checks that all DocLink components have an id, and the value of that id matches the frontmatter id of a page on the site.
• remark-elastic-transclusion: A custom plugin that checks that MDX JSX element nodes are defined. In Docsmobile-powered sites, this includes transcluded content.
• remark-elastic-variables: A custom plugin that checks that page-scoped variables are defined.
• *.docnav.json validation: A check that ensures all links in a *.docnav.json file are valid.

How it works

Here's how it works at a high level:

• [Temporarily] translates key asciidoc syntax to Markdown using a custom asciidocToMarkdown function so we can use the remark ecosystem. (Note: this is not robust enough to be used to convert content for the next docs migration, but does the trick to make content lintable.)
• Uses unified so we can use a combination of remark and retext plugins:
  • remark is tool that allows you to inspect and change Markdown with plugins.
  • retext is a natural language processor powered by plugins.
• Uses remark-parse or remark-elastic-asciidoc-parse as the parser, which gets a syntax tree from text.
• Uses remark-retext to check natural language in Markdown (using the plugins listed above).
• Uses remark-message-control to allow you to override rules on a line-by-line. See more in "Override rules" below.
• Uses remark-stringify as the compiler, which gets back from the syntax tree to text.
• Prints errors to the console.

The output looks like this:

12:56-12:59   warning  Replace `ILM` with `{ilm-init}`                          ILM        retext-use-attributes
28:28-28:36   warning  `indicies` is misspelt; did you mean `indices`?          indicies   retext-spell
33:115-33:120 warning  Replace `Fleet` with `{fleet}`                           Fleet      retext-use-attributes
41:2-41:11    warning  Replace `Heartbeat` with `{heartbeat}`                   Heartbeat  retext-use-attributes
47:73-47:81   warning  `indicies` is misspelt; did you mean `indices`?          indicies   retext-spell

Here's what's happening in the error in the first line:

• 12:56-12:59: These numbers tell you the line and column where the text causing the error starts (line 12, column 56) and ends (line 12, column 59).
• Replace 'ILM' with '{ilm-init}': The message in the middle describes the error and provides a suggestion.
• ILM: This is the keyword for the specific rule.
• retext-use-attributes: This is the plugin where the rule is defined.

Override rules

You can override rules at a couple different levels.

Override in all files

To override a rule across all files, add the name of the rule to an array and pass that array to the plugin using the ignore option. For example, ignore: ignoreAttributes is an option set for the retextElasticAttribute plugin above. ignoreAttributes is an array of attribute rules to ignore in data/overrides.js.

Override one or more lines

You can also override rules for a single line, a few lines, or one entire file using code comments in the content file. This is powered by remark-message-control.

For example, in the CI/CD Observability guide, we use the word "Visualisation" because that's how it appears in the UI even though we use American English and should typically use "Visualization". We shouldn't override this rule for all files. Instead, we can use inline overrides.

The ignore keyword turns off all error messages of the given rule identifiers (visualisation) occurring in the following node. The example below would allow you to use visualisation instead of visualization in the line after the comment.

<!-- lint ignore visualisation -->
Use the _Add Visualisation Observability Backend_ drop-down to select the *Elastic {observability}* option.

The disable keyword turns off all error messages of the given rule identifiers. The example below would allow you to use visualisation in all lines after the comment through the rest of the file.

<!-- lint disable visualisation -->
Use the _Add Visualisation Observability Backend_ drop-down to select the *Elastic {observability}* option.

Go to *Add Visualisation Observability Backend* and define the URL for your {kib} server.

The enable keyword turns error messages back on for a rule that was disabled. The example below would allow you to use visualisation in the lines between the comments, but would throw an error for the final line.

<!-- lint disable visualisation -->
Use the _Add Visualisation Observability Backend_ drop-down to select the *Elastic {observability}* option.

Go to *Add Visualisation Observability Backend* and define the URL for your {kib} server.
<!-- lint enable visualisation -->

More stuff about visualisation...

You can also use comments without defining a specific rule to skip all linting rules. The example below would not lint any of the text for spelling, style guide compliance, or any other rules you have set up.

<!-- lint disable -->
Use the _Add Visualisation Observability Backend_ drop-down to select the *Elastic {observability}* option.

Go to *Add Visualisation Observability Backend* and define the URL for your {kib} server.

More stuff about visualisation...

Publish to NPM

Once all changes are on the main branch, follow these steps:

1. From the main branch, make sure you pulled the latest using git pull.
2. Update CHANGELOG.md:
   1. Create a new ## X.X.X heading with the new version number after the ## Unreleased heading.
   2. Move all content from Unreleased under the new version heading.
   3. Commit changes with a message like "Prepare vX.X.X".
3. Run npm version X.X.X to increment the version number in package.json and package-lock.json. This will automatically create a commit and tag for the release.
4. Push your commits. (This will include both the CHANGELOG.md update and the automatically created commit.)
5. Run npm ci to make sure you have the latest dependencies.
6. Publish the new version on NPM using npm publish.

Update attributes reference

Note: The retext-elastic-attributes plugin uses a local data/attributes.json file. Right now it requires that you have the elastic/docs repository cloned locally in the same directory as this repository. I didn't want to invest too much in figuring out the best way to reference that data until we had a better idea where this would live and how it would connect to the rest of the docs infrastructure.

Get the attributes from your local copy of elastic/docs and format as JSON using:

npm run get-attributes

License

Apache License 2.0