[RFC] Docusaurus-plugin-linter-docs

Summary

I would like to propose the creation of a linter, to enforce best practices in the creation of docs, I passed-through a couple of weeks analyzing the viability of this project and I realize that is possible.

Basic example

docusaurus-lint api output

test2.md: 18: enforce-api-structure Enforces the structure of an API file [This current section is not following the recommended structure] ["<Title> <content> <code>"]

• First rules that I thought:
  • enforce-api-structure: ensure that a doc is following a recommended structure
  • check-cli-usage: check if after a cli command exists a image or gif showing the output
  • installation-should-have-requirements: check if before a installation section exists a requirements section
  • enforce-contributing-structure: ensure that a doc is following a recommended structure

disclaimer: The rules that enforce a structure will follow the pattern from the most-preferred by the users, a good example is the reactjs docs.

In a near future, i also think in add more purpose for our templates, so the template will follow the rules enforced by the linter, and when a user wants to create a new file for an api e.g., we could provide a template snippet with the recommended sections.

Motivation

In our sites, the users has a common visual identity, I mean, the user interface of the sites are very similar. Although, the visual is similar, the same is not applied in how the docs are structured, for example, they don’t follow a pattern in the docs structuring. We have different style of pages that do the same, like an api page, you can see the following examples: https://buildtracker.dev/docs/packages/api-client/ https://graphql-inspector.com/docs/essentials/validate

They do a similar thing, but in a different style, Why do not have a standard?

This can benefit the reader and the writer, if a user see a page with a pattern, the user can find the information that wants more easily, the job of a writer is facilitate the life of a reader. I think that this linter have a potential of be really useful for our users.

From what I saw, in the majority, we have three different types of users:

• Docs of APIs
• Docs of Component Libraries
• Docs about CLIs

The goal is provide a checker in their markdown structures about each type of documentation.

Detailed design

I thought in adapt our existing solution for plugins, in that we’ll have new plugins like docusaurus-plugin-lint-api, docusaurus-plugin-lint-cli, docusaurus-plugin-lint-components in a preset docusaurus-plugin-lint. This could benefitial for the user, since it allows a good opt-in option and extensible config, the user can enable and create the plugin(s) more appropriate for the use.

Since these plugins will parse a markdown structure, I thought in reuse the markdownlint and textlint

They have good rules that I could use to build docusaurus rules, and they also allow the users to create custom rules.

Existing Solutions

The existing solutions includes a big manual of best practices this discourages the users to read and adopt. You can check some of them below: https://developers.google.com/tech-writing/one https://www.ibm.com/developerworks/library/styleguidelines/ https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide

How we teach this

We can include a link for the lint documentation in our getting started page and possible include the lint as a configuration default in some of our templates.

If its possible, I would like to work on.

[slorber]

Hey, this is not totally related but I found out about this tool used on ReactNativeWebsite: https://github.com/get-alex/alex

[slorber]

Other option, is have an extension in the browser to show the errors, so when he is manipulating .md files the extension could point the lines with errors

The problem is that it would be hard to ship custom rules of a third-party site in a a browser plugin. I use a Prettier plugin and it works great, but it works only because all the rules are shared for everyone.

I don’t know if I really understood what this mean, Could you explain with other words?

Actually I’m taking notes everytime I see this problem, when we have to ask someone to manually backport doc changes from one version to another.

https://github.com/facebook/docusaurus/pull/2886#pullrequestreview-425061370 https://github.com/facebook/docusaurus/pull/2966#issuecomment-646435274 https://github.com/facebook/docusaurus/pull/2973#pullrequestreview-434475702

I think this is something annoying (common to many snapshot versioned websites, not necessarily D2), and I’m interested to find a solution, so that the contributor knows ahead of a human review that his PR is “incomplete”

But this is probably out of scope, as it’s not related to the markdown content of the doc.