📝 Tips for working with Markdown

Markdown is now a nearly universal format for documentation in many workflows. A few tips for being effective with Markdown:

Use a standard editor most of the time (VS Code, Vim, Helix, etc.). This is faster than graphical "Markdown" editors for most things. Additionally, this builds familiarity with Markdown formatting codes, which aids in creating nicely formatted comments in Jira, GitHub, Trello, etc.

Use Typora to create more complex things like tables and images. This tool is well worth the few $$ it costs.

Put images in an /assets sub-directory and name image files descriptively (Typora makes this easy).

Use prettier to format the file and wrap long lines. Add a .prettierrc to every repo with the following contents: proseWrap: always

Use Harper (language server in your editor is best) to check for grammar and formatting issues. One unexpected side effect of this is that it encourages marking technical words that don't have standard spelling as code, rather than adding them all to your dictionary.

Add dictionary words to a .harper-dictionary.txt in the repo that contains the markdown file. This way others can benefit from a common dictionary. Again, this is easy with a harper-ls quick-action.

Add a TOC if the file is long (the harper-ls quick-action makes this easy).

Use the Marksman language server. This makes navigating and refactoring in your editor easy.

Use Markdown Here or Markdown Here Revival in your browser or email client to write better emails.

While Markdown has its formatting limitations, with a little tooling it is much easier and faster to work with than anything else.