[RFC] Docusaurus-plugin-linter-docs

[fanny]

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]

Hi,

I'm interested to explore this, but not totally sold yet :p

Do you see this being applied somewhere in the D2 website? That could be nice to do a POC on D2 website and see if we find value in it.

Do you know D2 users that would like this kind of feature? I think we should find some and understand their usecases, or try to pitch/poll the community to create the need.

Do you see shared patterns between the writing style guides that could be added as a lint rule?

[fanny]

Hey,

Do you see this being applied somewhere in the D2 website? That could be nice to do a POC on D2 website and see if we find value in it.

Yeah, most of the patterns that I commented the docusaurus already follow, for example in our API doc, we have:

• title: the method name or component name
• content: a paragraph explaining the method or component
• usage: the code

this page have an example: https://v2.docusaurus.io/docs/docusaurus-core

Do you see shared patterns between the writing style guides that could be added as a lint rule?

The same is applied for the users like:
Build Tracker
GraphQL Code Generator
GraphQLMesh
GraphQL Inspector
Facebook Watchman

Do you know D2 users that would like this kind of feature? I think we should find some and understand their usecases, or try to pitch/poll the community to create the need.

I don't know specific users that would have interesting in this feature, but I tend to think, that they probably will want if we offer, this can facilitate the life of docs contributors, because they will have a tool to ensure that they will follow the project pattern, the reviewer too because they only need to focus on the content, and the reader because having a structure in common among pages helps to focus on the interesting parts.

[fanny]

I'll create a POC

[slorber]

About the examples you linked to, I see some similarities, but also a lot of potential differences.

Let's take these:

• https://buildtracker.dev/docs/packages/api-client/: title description code
• https://graphql-inspector.com/docs/essentials/validate: title description code subtitle description code api example code args output

If we are building an opiniated docs markdown linter, I'm not sure what rule could validate those 2 files, that both looks valid api docs to me.

This can be useful, just thinking the rules are quite subjective, and not sure how to design these rules in the first place so that our opinion is good for most users.

Also, it could be useful to other docs projects relying on markdown. This could be a totally separate opt-in package, that users of Gitbook/Jekyll or other static sites using md could use as well. (can still be in this repo, as
@docusaurus/docs-linter or somethinh?, as it can help docusaurus get known to a broader audience as well)

[fanny]

it's quite hard try to describe a general rule that cover all the cases, my idea is not do this, is more to help users when they are creating your docs, and also to have a linter engine that allow the rule creation more easily, for example, in the previous case, we could ask to the user instead of the template, provide the regex that will be applied on the pages.

I also loved the idea of ​​separating a docusaurus package without attaching it to the plugin architecture, you're right here we have a potential use in other SSRs

[slorber]

I think we should try a poc on D2 website. If we find value in such tool, other people will likely find value too.

One concern if that many docs edits are done through the git interface so that an user does not need a fork etc... I guess we'll show the docs linting errors in PR checks and he'll be able to fix this, but the feedback will be a little delayed.

One rule that would be interesting, (and it's not really related to md actually), would be to ensure that contributions in version X are also contributed to version next (maybe it's a separate subject)

[fanny]

I think we should try a poc on D2 website. If we find value in such tool, other people will likely find value too.

Okay, I'll do, using the docusaurus pages as a template

One concern if that many docs edits are done through the git interface so that an user does not need a fork etc... I guess we'll show the docs linting errors in PR checks and he'll be able to fix this, but the feedback will be a little delayed.

Yeah, Its a good idea integrate with a CI / CD. 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, but I don't how complex it is, and if it is worth the effort, it's just a thing that I thought as an alternative.

One rule that would be interesting, (and it's not really related to md actually), would be to ensure that contributions in version X are also contributed to version next (maybe it's a separate subject)

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

[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.

#2886 (review)
#2966 (comment)
#2973 (review)

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.

[slorber]

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