I was getting some reoccurring issues when publishing my markdown documents, let's just call them bugs for simplicity, I will discuss them in more detail later. So, I decided to re-evaluate my workflow.

My personal preference is to do my writing in a desktop application called Typora. It's similar to a word processing application, it offers less distraction, I like using its "focus mode", it has spellchecking, and shortcuts for formatting text. I use Jekyll for my blog. I do a quick review locally in the browser, before I push it to github, which takes care of publishing.

Typora covers most of what I want, but over time, I have found some syntax errors creep into my documents, which I didn't always catch. So, some sort of linting would be nice. And I would like some additional features such as adding a table of contents (TOC), anything that is a bit tedious to write manually, and can be error-prone.

Ideally, I would use one application to do everything, but realistically getting everything I want in one application is probably only possible if I configure an IDE to suit my preferences.

I will explain what is "bug-free" publishing for me, and what tools are available to help improve the quality of your markdown documents.

TLDR

I configured VSCode to get closer to my "bug free" publishing ideal. I continue to use Typora for my drafts, and use VSCode for final editing and publication!

"Bug-free" publishing

"Bug-free" publishing is ensuring that there are no unintended or undesirable results when you transform your markdown to HTML, and push it to wherever you like to publish. Here are some tasks you may want to include to your workflow:

1. Syntax checking (linting). Ensure that your markdown is correct. Applications don't have this, you need to use an IDE with a linting plugin, or a task runner.

2. Spellchecking. No tpyos! 😉 Most applications have spellchecking by default, most IDEs don't.

3. Use the same markdown syntax everywhere. There isn't that much difference between markdown and its related variant syntaxes, but it is good to be consistent with what you see in your preview, and what your target platform (processor) uses under the hood. I want to use github-flavoured markdown everywhere.

4. Format on save. You may want to use automatic formatting on your document to remove egregious formatting mistakes, and ensure consistency.

5. Checking validity of images. This is specific to my set-up. I noticed that the editors I used and Jekyll (my static site generator) have different expectations for file paths. For example, look at the folders in the picture below, if I want to embed the image banner.png in my markdown file, most applications expect ../img/banner.png, Jekyll expects /img/banner.png. I would like my editor and the static site generator to agree.
   

6. Generation of a TOC and section numbering. Cut out manual creation and maintenance of these.

Tools

I will quickly list some of the options for tools you may want to use outside of your editor, or as an integration in your editor (if possible). They can be used as CLI tools, in task runners, as a github action,, or as a plugin for some IDEs.

Linting

1. MarkdownLint: Style checker and linting tool available in a few languages.
2. Textlint: Offers markdown and natural language linting with many integrations.

Spellchecking

1. markdown-spellcheck:Reads markdown files and spellchecks them. It uses open source Hunspell dictionary files. Written in JavaScript and available on npm.

Configure VSCode for all your markdown needs

VSCode has decent "out of the box" support for Markdown. VSCode covers this in its docs: VSCode and Markdown.

"Out of the box" features

1. Supports the CommonMark Markdown specification.
2. Live preview. You can open a live preview of your active markdown document.
3. Preview and editor scroll synchronisation. If you want to view the markdown and preview side-by-side, you can have them scroll in unison.
4. Outline view. It shows a symbol tree of the document's header hierarchy.
5. There is no spellchecking.

Additional features I would like

1. Support for Github-flavoured Markdown specification.
2. Linting (code analysis)
3. Spellchecking
4. A different theme for markdown to serve as visual reminder that I am in a different context.
5. Generation of a TOC and section numbering. Cut out manual creation and maintenance of these.

My configuration

I settled on using the following extensions:

1. Markdown All in One for: GitHub-Flavored Markdown support, creation of a table of contents, section numbering, keyboard shortcuts, and autocompletions.
2. markdownlint for linting and some formatting. I chose to use all of the default rules, and I have changed some rules after using it with some existing documents. I prefer to choose when to fix violations myself.
3. Prettier for formatting on save. This will format the code blocks based on the language, it it supports it. It doesn't appear to reformat anything else.
4. Theme by language to set a specific theme for markdown.
5. Spell Right for spellchecking.

In the Problems tab: spelling problems are listed as errors, and linting problems are listed as warnings.

My User Settings (settings.json)

{
   ...

  "[markdown]": {
    "breadcrumbs.showClasses": true,
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "markdownlint.config": {
    "default": true,
    "MD003": {
      "style": "atx"
    },
    "MD010": {
      "code_blocks": false
    },
    "MD026": {
      "punctuation": ".,;:"
    },
    "MD033": false
  },
  "theme-by-language.themes": {
    "markdown": "Markdown Editor",
    "*": "Monokai"
  }
}

Final Words

In word processors like Microsoft Word and OpenOffice Writer, you take for granted a lot of the features that help you craft well-written and well-formatted prose. Applications for markdown don't have that same rich feature set, and you have the additional concern of adhering to a syntax.

I found it a worthwhile investment to tweak my workflow to keep my writing experience pleasant, while improving the quality of my output. I am still making adjustments here and there.

Happy writing! 🙌✍

Cover Photo by JESHOOTS.COM on Unsplash