MarkdownDox is a simple documentation tool for Visual Studio Code. It is designed to help Technical Writers (or any writers for that matter) to utilise Visual Studio Code's Markdown editing capabilities to easily create documentation which outputs to static HTML and PDF files.
Don't expect all the bells and whistles; this extension just does the basics.
The following functions are available to the user:
Markdown-It plugins included
Markdown-It plugins included in MarkdownDox:
A sample of the extended Markdown that these plugins enable can be seen by clicking the link below.
MarkdownDox can be complemented with the extensions listed below to make the task of documentation simpler for you.
Install from Visual Studio Code
Install MarkdownDox from Visual Studio Code:
Install from a VSIX file
Install the MarkdownDox Visual Studio Code extension from a VSIX file on the command line:
MarkdownDox does not have any extension-wide configuration options. All configuration is done at the project level.
Each MarkdownDox documentation project has its own project configuration file titled
The project configuration file uses the JSON file format. Configuration values can be independently set for each project.
Project configuration options
Below are the available project configuration options with default values.
project_name: "My MarkdownDox Project"
The name of the documentation project.
The folder where project images are sourced from, relative to the project root folder. This folder and all of its contents will be copied to the output folder. Only one level of sub folder is supported within this folder, e.g. "./images/aircraft" will be copied to the output folder but "./images/aircraft/helicopters" will not.
The folder where project stylesheets are sourced from, relative to the project root folder. This folder and all of its contents will be copied to the output folder. No sub folders within this folder will be copied.
The folder where project includes are sourced from, relative to the project root folder. This folder and all of its contents will be copied to the output folder. No sub folders within this folder will be copied. Include files are not processed recursively. In other words, include statements within include files will not be processed.
To include an include file in you Markdown, add the
The folder where project output files are written to. Any existing files are overwritten. The images and stylesheet folders are deleted and re-copied from the project image and stylesheet folders each time a new HTML output file or set of HTML output files is created.
The path to the project stylesheet, relative to the project root folder. This stylesheet is used to style each output HTML and PDF file created.
The path to the project highlight stylesheet, relative to the project root folder. The highlight stylesheet is used for syntax highlighting of code content in each output HTML and PDF file created.
If true, then the contents of the stylesheet configured in the stylesheet_path option will be copied into the <head>..</head> section of the output HTML file and placed within the <style>...</style> tags.
If false, a <link> tag will be added within the <head>..</head> section of the output HTML file, linking to the stylesheet configured in the stylesheet_path option. For example:
The list of Markdown files which are included as part of the project. The files listed here are each generated as separate HTML files when the user selects to Generate HTML from all project files.
If a file is not listed here, it will not be generated as HTML during this process.
If true, when an include file is not found during processing, a message is inserted into the output HTML file -
If false, the output HTML file is generated without the missing include content.
If true, the project include files
If this option is set to true and you do not want to include content for the header, footer or navigation, then leave the appropriate file contents blank. For example, if you do not want to have navigation (Table of Contents), then leave the
If false, then only explicitly declared
To include header, footer and navigation when this option is set to false, add the
If true, a page break tag
When the resultant single Markdown file is made into a PDF file (by selecting Make PDF from this file or as part of the Make PDF from all project files process), each page break tag will result in a page break in the output PDF file.
The list of Markdown files which are included as part of the project when generating a single Markdown file for use in making a PDF output file.
The files listed here are each processed and joined together, in the order they are listed, into a single Markdown file. This happens when the user selects to Combine all project Markdown into a single file or to Make PDF from all project files.
This setting allows the PDF output to include more or less content than the HTML output. For example, the PDF file may include a document control section which is not needed in the HTML output.
If a file is not listed here, it will not be included in the single Markdown file or the output PDF during this process.
pdfHeaderTemplate: " " Note: It is important to keep a space between the quotes if you do not want to display any header content in the PDF output.
pdfFooterTemplate: "<div style="width: 100%; font-family: Arial; font-size: 9px; margin 0 auto; text-align: center "><span style="margin-left: 20px;">Copyright © 2019 My Company Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>"
Read about how to use MarkdownDox on the Getting started page.
Supported Markdown Syntax
See a sample of supported Markdown syntax on the Sample page.
Creating custom stylesheets
Customise the look of your HTML and PDF output by creating custom stylesheets.
None yet. :)
Initial release of MarkdownDox.