This template provides a markdown editor environment for vscode. Use it to compose documents in md format and then convert to docx, html, or pdf using the vscode-pandoc extension. The setup mainly follows this tutorial.
This example assumes that you have forked this template and (optionally) cloned it to your local environment. If not, see Setup below. Once you have done that, you can create a new local md editor environment that will also exist as a public repo on your github.com account in one line. First, navigate to the local directory where you want to create your new repo, just as though you were cloning a remote repo. Then try:
gh repo create <your-new-repo> --public --template=<your-github-username>/<this-repo>So long as you have the gh cli installed, that one-liner should clone this template as it exists on your github.com account into <your-new-repo> in your local environment and create an upstream public remote on your github.com account.
Once you have a working copy of this template, feel free to use your Git hooks prowess to circumvent the gh-based method above anytime you need to compose a new set of Readme's, take notes on a workflow, review a manuscript, write a letter, or anything else you would do in a md editor, without ever leaving your vscode environment (or opening Word).
-
Fork or clone this repo
-
Install pandoc however you want
-
Install vscode-pandoc extension
- Press F1 to open the VS Code Command Palette
- Type ext install vscode-pandoc and press enter to find the extension
- Press Enter or click the cloud icon to install it (I used the one by Doug Finke)
- Restart Visual Studio Code if prompted
-
Install markdown linter
- Press F1 to open the VS Code Command Palette
- Type ext install markdownlint and press enter to find the extension
- Press Enter or click the cloud icon to install it
- Restart Visual Studio Code if prompted
-
Edit the following to your liking
css/.markdownlint.json.vscode/settings.json- I followed the tutorial and used this css style sheet from here as a starting point and then changed the code font color to black and removed the italics for level 2 subheading.
-
Test it out using
test.md(see next section). -
Optional: let vscode know to render your md preview using your preferred css style by adding this to
settings.json, either in the Workspace settings (as it is in this repo) or in your User settings:"markdown.styles": [ "css/style.css" ],
-
Note: the vscode preview rendered code with yellow font so I added a color attribute to the code container in style.css.
Place cursor anywhere in an open md file, press command+k (then release), then press p, and options to convert the md file to docx/html/pdf should appear in the vscode command palette. The converted file is saved in the same directory as the md file.
Didn't work? Did you press command+k and then release before pressing p?
Note: the preview generated by vscode may differ from the html version. I suggest rendering the html before fiddling with the stylesheet.
Pandoc enables the conversion md to html, docx, pdf, etc. It must be installed and accessible to the vscode python interpreter.
The markdown helper extension was recommended in the tutorial because it makes tables easier, but I chose not to install it because reviews are poor. It seems to be outdated. Instead I installed the highest rated extension Markdown All in One. I did not investigate options to integrate that extension with this environment.
Install Code Spell Check extension or similar.
/markdownlint.json enables us to customize the rules used by the markdownlint extension.
/css/style.css is used by html generated by pandoc.
/.vscode/settings.json is the workspace version of the global vscode settings.json file. It was essential to change the pandoc.pdfOptString to achieve acceptable pdf rendering.
/.vscode/extensions.json I think this was auto generated by the vscode-pandoc extension.