Table of Contents

Overview (TL;DR)

In a nutshell, mdEditor is a VS Code Workspace that can be installed from GitHub. It creates a sort of self-contained Markdown environment on your local machine.

mdEditor provides the configuration guidelines and creates the structure for an awesome VSCode Markdown editor. By creating a reusable Code-Workspace, the main portion of your IDE environment is protected from rule conflicts.

Features

  1. The Code-Workspace, once opened with VS Code, loads everything you need for importing, exporting, linting, custom rulesets, automatic styling, and file conversion --> PDF, DOCX, and HTML.
  2. The syntax rules allow for the enforcement of any markdown flavor with a simple on/off option for each rule.
  3. The linter looks for errors/problems and immediately flags them. A detailed explanation and reference link will appear on hover.
  4. The auto-fix feature is enabled by default to run each time a file is saved. This formats your Markdown using the enabled rules, which corrects most errors automatically with no manual edits needed.
  5. The file conversion tool uses an extension to integrate Pandoc with VS Code. With a simple key-binding ( CTRL + K , P ), you can create .pdf , .docx , and .html files from Markdown, after which the new files can be viewed immediately and/or exported elsewhere.
  6. The default stylesheet is applied during file conversion, ensuring uniformity and consistency in the output. You can apply custom styles using CSS to achieve the desired appearance of the converted files.

Prerequisites

Visual Studio Code This should be self-explanatory.

Pandoc This may require some guidance if you don't currently use Pandoc. I wrote a gist to help first-time users; here is the link.

Installation

mdEditor can be installed using the simple guide you are reading now, which paraphrases the README.md file from the main repository.

Decide where the root directory of the editor is going to live on your local drive (reference Overview for details), then clone mdEditor to that location.

Now, open mdEditor at the base directory using VSCode. Your IDE will auto-discover the .code-workspace file and prompt you to reopen the folder as a workspace.

Confirm this choice, unless you want a different configuration. If so, there is a blank settings.json in the .vscode folder for you. Otherwise, just delete that file to avoid confusion.

Once open, you should receive another prompt to install the recommended VS Code extensions. Once again, choose confirm to install, and leave the default settings in place.

The extensions will power the linting rules and Pandoc style guide within the workspace. Here are the links in case you encounter any issues.

--> markdownlint --> vscode-pandoc

Now, using this diagram, verify the file structure of your local installation of mdEditor is a rough match.

    **Tree View**
    _mdEditor_
    \+---.vscode
         |       `
settings.json
`
         |
         +---md
         |       `
project1.md
`
         |       `
project2.md
`
         |
         +---styles
         |       `
style.css
`
         |       `
syntax.md
`
         |
         |`
.markdownlint.json
`
         |`
mdEditor.code-workspace
`
         |`
README.md
`
         |`
LICENSE
`
         \---

NOTE: On Linux you must uncomment the pandoc.htmlOptString in the mdEditor.code-workspace file. The current version, which uses Windows OS file separators, must be replaced with the Linux version; otherwise, the css styles will not be applied correctly.

Installation is complete. Nice job!

Usage

To test linting & formatting, click the test.txt file (in the md folder); it should open in the main editor window.

In the sidebar, keeping the test.txt tab in focus, change the filetype from txt to md and save.

Check the output in the PROBLEMS tab of your lower (terminal) panel. Several formatting violations should appear. Now make a tiny edit and save again. Most of the errors should be gone, having been corrected automatically.

To test the filetype output, enter the key combination CTRL + K , then press P . Options to create .pdf , .docx , or .html file should appear in the dropdown. Click each option in turn and confirm the desired result was produced.

Workspace setup is now complete and mdEditor is ready to use.

NOTE: The syntax.md file in the styles folder contains a detailed description of the linting rules available within the editor workspace. Any rule can be toggled on/off by editing the .markdownlint.json file using this syntax. "ruleID" : bool

Happy markdown'ing! :)

Don't forget to 💖 this article and leave a 💭. If you're feeling extra generous, please click my name below to 🎆subscribe🎇!

-- killshot13

Credits

Extensive credit is owed to Dave for indirectly inspiring me to create mdEditor after reading this guide he authored.

mdEditor is free software released under the MIT license. Copyright 2020-2021 Michael Rehnert

All software programs, extensions, plugins, and digital content referenced and/or used in the documentation and/or installation guide of mdEditor is the respective intellectual property of the creators, developers, and owners thereof and is entitled to the protections granted under U.S. Copyright law.

This post is also available on DEV.