... | @@ -819,6 +819,28 @@ it's able to make changes inline. |
... | @@ -819,6 +819,28 @@ it's able to make changes inline. |
|
[nodejs markdownlint]: https://github.com/DavidAnson/markdownlint
|
|
[nodejs markdownlint]: https://github.com/DavidAnson/markdownlint
|
|
[codespell]: https://github.com/codespell-project/codespell/
|
|
[codespell]: https://github.com/codespell-project/codespell/
|
|
|
|
|
|
|
|
#### Vale
|
|
|
|
|
|
|
|
Vale is interesting: it's used by both GitLab and Grafana to lint
|
|
|
|
their documentation. Here are their (extensive) rule sets:
|
|
|
|
|
|
|
|
* [Grafana](https://github.com/grafana/writers-toolkit/tree/main/vale/Grafana)
|
|
|
|
* [GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) (only one of the configurations, [their guide has
|
|
|
|
more](https://docs.gitlab.com/ee/development/documentation/testing/vale.html))
|
|
|
|
|
|
|
|
In a brief test against a couple of pages in TPA's wiki, it finds a
|
|
|
|
*lot* of spelling issues, mostly false positives (like `GitLab`, or
|
|
|
|
`Grafana`), so we'd have to build a dictionary to not go bonkers. But
|
|
|
|
it does find errors that codespell missed. We *could* bootstrap from
|
|
|
|
[GitLab's dictionary](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/spelling-exceptions.txt), hooked from their [spelling rule](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Spelling.yml).
|
|
|
|
|
|
|
|
#### mlc
|
|
|
|
|
|
|
|
[mlc](https://github.com/becheran/mlc) was tested briefly as part of [the check links issue](https://gitlab.torproject.org/tpo/tpa/ci-templates/-/issues/14) and
|
|
|
|
found to not handle internal GitLab wiki links properly (although that
|
|
|
|
might be a problem for all link checkers that operate on the source
|
|
|
|
code). It also [doesn't handle anchors](https://github.com/becheran/mlc/issues/31), so it was discarded.
|
|
|
|
|
|
### Charts and diagrams
|
|
### Charts and diagrams
|
|
|
|
|
|
We currently use [Graphviz](https://graphviz.org/) to draw charts, but have also used
|
|
We currently use [Graphviz](https://graphviz.org/) to draw charts, but have also used
|
... | | ... | |