Ideas for docs CLI / CI toolchain automation and extensions

[ScriptAutomate]

Summary

We should evaluate implementing tools in documentation repositories that can help in automating formatting, spelling, and style standards. A side benefit of this will mean that others can make use of our own implementations to use in their own projects, ultimately enforcing good practices and writing standards within their own notes and docs.

Details

Areas of interest, commonly issues for docs management:

• Spelling
• URL validation (both internal and external)
• Opinionated file formatting (for yaml, json, markdown, etc.)
• Linting / finding formatting errors (for yaml, json, markdown, etc.)
• Finding problems furthest left in contributing pipeline (ex. locally, with git hooks and/or tools like husky or pre-commit)
• Automated writing style auditing/guidance (includes grammar)

Tools

Tools of interest to evaluate.

• prettier: Automated formatting of yaml, json, md, etc. files
• markdownlint-cli: Markdown format linting. Not sure what problems Dendron markdown (wikilinks, not refs, etc.) may introduce here, but the CLI allows for custom rules
  • Evaluate difference with markdownlint-cli2
  • Evaluate compatibility with vscode-markdownlint
  • Related issue: Linting against the "canonical" format #279
• spellchecker-cli (or other spellcheck CLI tool): Supports custom dictionary for words that otherwise should fail
• brok (or other external URL validator): External URL validator, hosted in the CI. Uses cache to prevent referencing same URLs every day (expires after 1-month). brok itself has not been maintained/updated in a while...
  • Potentially of interest: Replace usage of brok with blc or equivelant npm package dendron-site#183
• Dendron: Doctor commands:
  • findBrokenLinks: Find any internal, broken Dendron links. Would be great as a test that must pass before PR is merged.
  • fixFrontmatter: Could auto-run this against vaults, in the event that newly introduced notes have broken frontmatter?
    • Extend fixFrontmatter to support something like checkFrontmatter?
• husky: Auto-run commands able to be run locally before a commit is made, catching as many problems as possible (broken yaml formatting, apply prettier before committing, etc.)
  • Alternative: pre-commit (Python-based instead of Node)

Prose and Style Auditing

There are many tools out there, here is a snapshot of them:

• write-good: Opinionated English prose style analyzer
• proselint: Opinionated English prose style analyzer
• vale (cli): Style guide and spelling evaluations
• RedPen: Style guide and spelling evaluations
• alexjs: "Catch insensitive, inconsiderate writing"

Approach

I feel that we'd likely want to approach tool automation be first introducing it into a smaller set of documentation, perhaps starting with The Open PKM Catalogue (Source)? Or maybe seed onboarding repo? Otherwise, dendron-site would be the repo that - if the tools work - can be rolled out elsewhere after.

We'd likely want to get one tool introduced one at a time, starting with a handful of easier wins:

• External URL validation in GitHub Actions CI
• prettier
• markdownlint-cli
• Dendron: Doctor commands
• Perhaps prettier?

Benefits of this approach:

• Can be applied by contributors directly within the VS Code editor via extensions, as each of these have extension equivalents

Problems to keep in mind

As we start to introduce other tools, they may require additional setup on behalf of the contributor. This can begin to create a barrier to contributing.

• husky: This is a nodejs tool, so requires additional node reqs. This may not be so much an issue with people already using CLI
  • pre-commit: This is a Python-based tool, so requires Python and installation of pre-commit
• Tools like vale: Another third-party piece of software that needs to be installed. The VS Code extension experience is really clunky, and if you open a project that doesn't have a Vale config, the extension is annoyed
• Really anything that requires further tooling steps required by the contributor outside of VS Code. Then again, CI will help show anything they otherwise may have caught locally, and a reviewer could automatically apply fixes to the persons PR, or provide direction (linking to docs contrib documentation) on how the contributor could approach

What about accessibility?

There is another GitHub Discussion around this:

• Accessibility #2165 (comment)

Asks

• Are there other tools of interest that would be better than the ones listed, or that should be considered?
• Are you interested in contributing by testing out these tools?

[SeriousBug]

Instead of "fixFrontmatter", perhaps we could add a "checkFrontmatter" command that only reports if there are broken notes. That would be useful as a pre-commit or pre-push check on all our internal vaults too.

For the pre-commit, we could use husky since most people working on Dendron are likelier to have nodejs. But I can still see that being a barrier of entry, say for someone on Windows who doesn't work on Dendron but wanted to contribute to the documentation.

[ScriptAutomate]

• Updated to include husky
• Added note about a checkFrontmatter option idea

[rlh1994]

I'd be up for supporting any CI testing (within the context of gitlab - given my issues anyway!) Even if it's just converting GH action yml to gitlab CI/CD. As it's something I've wanted to get some learning in for a while, but I'm very new to it all so there may be someone better to help.

[ScriptAutomate]

This might be good to keep in mind in deployment. As in, could have something like a scripts directory at the workspace root that the CI tooling calls. I think it would be great if in the future we just had a dedicated repo of these scripts/configs/style guides/etc. which could be pulled in and then called. It would make it easier to then be imported and used by multiple repositories.

But, I don't know how super-specific certain configurations will become to each docset, either.

[ghost]

Well, the scripts folder could hold the actual scripts that do the work, while certain Tools have a config file, the dedicated repo could hold sane defaults while each docset could have custom configs that are only for that docset needed.

[ghost]

While I support the auto running of certain tools during pre-push, all checks and Validation should still be run as PR/MR checks to make certain that the pre-push runs didn't get prevented or failed to run, etc.

[ScriptAutomate]

Totally agree. The idea would be that the first job to run in CI would be the husky or pre-commit job that should also be running locally, as a way to catch whether it was run locally or not

[ghost]

If Husky is chosen in the end, I think it would be wise to use okonet/lint-staged to somewhat reduce the file amount that needs to be linted.

This could also be used to check Assets and configs since we can filter what to run for which file ending.