facebook / facebook/docusaurus

[RFC] Docusaurus-plugin-linter-docs

Abierto
#2,965 9 comentarios 7 reacciones 0 asignados Ver en GitHub
domain: dx proposal
Lenguaje dominante
TypeScript
Estrellas
66.2k
Forks
10k
Merge medio
1 d 3 h
PR fusionados (30 d)
52

Descripción

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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.