dendronhq/dendron-site

Use tooling to enforce, and prevent conflicts with, a documentation Style Guide

Opened this issue · 0 comments

ScriptAutomate commented

Follow-up to #333

Use tooling to enforce, and prevent conflicts with, a style guide.

We should look at something like Vale, and pair with pre-commit. This would help with a variety of things, but could start with one:

  • Inconsistent capitalization, or otherwise different forms of case

This may be something more like three separate issues:

Potential Issues

  • Base Dendron dictionary
    • Including terms in this issue
  • pre-commit application of Vale, and other project standards
    • Would need to include contributor documentation for installing/using pre-commit
  • Spellcheck, using something like Vale or codespell or other solution
  • Style guide checking use Vale (ex. Google Style Guide)
  • Process for updating/syncing with latest style guide, using something like Vendir
  • Implement something like behave (or TypeScript equiv) to actually test the style guide via BDD, ensuring that it is working as intended

Term Dictionary Example

Examples to include:

next.js|NextJS|Next.js
markdown|Markdown
markdown based|Markdown-based
github|GitHub
github actions|GitHub Actions
linkedin|LinkedIn
vscode|VS Code
twitter|Twitter
dendron|Dendron
obsidian|Obsidian
json|JSON
jekyll|Jekyll
dendron cli|Dendron CLI
vim|Vim
pdf|PDF
css|CSS
obsidian|Obsidian
youtube|YouTube
svg|SVG
js|JS
scss|SCSS
dendron//|dendron://
cli|CLI
edge browser|Edge browser
react|React
emacs|Emacs
sublime text|Sublime Text
microsoft word|Microsoft Word
now a days|nowadays
vs code insider|VS Code Insider
elasticsearch|Elasticsearch
vscodium|VSCodium
evernote|Evernote
github flavored markdown|GitHub Flavored Markdown
facebook|Facebook
github pages|GitHub Pages
wikipedia|Wikipedia
dendron next|Dendron Next
seed membership|Seed membership
dendron markdown preview|Dendron Markdown Preview
discord|Discord
rfc|RFC
gitlab|GitLab
foam|Foam
roam|Roam
chrome|Chrome
firefox|Firefox
google|Google
gmail|Gmail
airtable|Airtable

Using Vendir

Now that I think of the Vendir stuff, examples of it being used in another open source project salt-user-guide:

Other thoughts

I can see this style guide being something that exists in a standalone repo under the dendronhq org, so that the style guide:

  • Is portable/reusable. Making it easier so that it can be used by anyone in their own vaults/workspaces/projects