Awesome Markdown Editor/Workspace for VS Code

v2.0.0

• About
• Prerequisites
• Installation
• Usage
• References

• Auto-checks for errors/problems and generates a detailed output for any broken rules.

• Lints and runs auto-fix on save which will correct/reformat most common errors.

• Supports the creation of .pdf, .docx, and .html files, which can be exported and viewed with MS Word, Adobe Acrobat, or the browser.

• Enforces syntax for any markdown flavor with a simple on/off option for every rule.

• All html files are linked to a basic stylesheet during creation so they look natural if viewed with the browser.

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.

Unless you work with Markdown on a daily basis, the editor is designed to be installed locally at the user level. Markdown files can be created in the editor workspace, and existing files imported as needed for easy linting.

mdEditor is an adaptation derived from the brainchild of Dave Johnson, which he detailed a couple years ago in an article on his blog.

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.

Decide where the core mdEditor files should live on your local drive (reference About for more), 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 wish to use a different configuration.

If so, there is a blank settings.json in the .vscode folder for you. Otherwise, you should disregard said folder completely.

We still need to pass the linting rules and Pandoc style guide to the editor workspace.

You should have noticed a prompt once you entered the workspace about installing the recommended extensions. If you have not done so already, go ahead and approve the install.

If for some reason you did not receive a prompt or have already closed the notification tab, not to worry. Just install these VSCode extensions, leaving the settings at their default values.

--> markdownlint

--> vscode-pandoc

Now, using this diagram, verify the file structure of your local mdEditor is free from any discrepancies.

• .github
  • ISSUE_TEMPLATE
    • bug_report.md
    • custom.md
    • feature_request.md
  • CONTRIBUTING.md
  • ISSUE_TEMPLATE.md
  • PULL_REQUEST_TEMPLATE.md
• .vscode
  • extensions.json
  • settings.json
• images
  • markdown-to-docx.jpg
  • markdown-to-html.jpg
  • markdown-to-pdf.jpg
  • mdEditor.gif
• CHANGELOG.md
• LICENSE
• md
  • test.txt
• mdEditor.code-workspace
• styles
  • style.css
  • rules.md
• README.md

If the file structure matches, installation is complete. Well done!

NOTE: If using 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.

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. Most linting rules can be simply toggled on/off by editing the .markdownlint.json file using this syntax.

{
	"MD-XXX": Boolean
}

Happy markdown'ing! :)

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

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

Additional credit and appreciation is extended to the creators, contributors, and maintainers of the following open-source software projects.

markdownlint is free software released under the MIT license. Copyright (c) David Anson

vscode-pandoc is free software released under the MIT license. Copyright (c) 2023 Chris Ward / aka Chris Chinchilla

Pandoc is free software released under the GPL. Copyright 2006–2022 John MacFarlane.

VS Code is free software released under the MIT license. The project's source code is available on GitHub. Copyright (c) 2015 - present Microsoft Corporation

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.