facebook / facebook/docusaurus

[RFC] Docusaurus-plugin-linter-docs

Ouverte
#2,965 9 commentaires 7 réactions 0 personnes assignées Voir sur GitHub
domain: dx proposal
Langage dominant
TypeScript
Étoiles
66.2k
Forks
10k
Merge moyen
1 j 3 h
PR mergées (30 j)
52

Description

# 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] [" <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](https://github.com/DavidAnson/markdownlint) and [textlint](https://github.com/textlint/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](https://v2.docusaurus.io/docs/installation) page and possible include the lint as a configuration default in some of our templates.

If its possible, I would like to work on.

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.