MarkdownDox

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.

Features

• Powered by Markdown-It markdown parser with additional plugins to provide an extended Markdown syntax
• Per project configuration file
• Support for Markdown include files to include common content within Markdown files, such as header, footer, etc.
• Provided with a set of flexbox based stylesheets designed to be responsive for the multiple screen sizes, including laptops and mobile phones
• Outputs HTML5 semantic HTML layout, including <header>, <nav>, <section>, and <footer> elements
• Generates PDF files using Google Chrome's puppeteer framework
• Options for internal or external stylesheets
• Output to a configurable output folder
• Create and use your own custom stylesheets if desired
• Provides a single point of navigation in a configurable, project-level Table of Contents (read from an include file)
• The option of including a page-level Table of Contents
• Written in Javascript, using Node.js as its processing engine
• Designed to be simple and easy to use for less technical users
• Output is designed to be readable in HTML or PDF without a connection to the internet, for instance in locked-down computing environments where internet access is restricted

Functionality included

The following functions are available to the user:

1. Create a new MarkdownDox project - Ctrl+Alt+n
2. Combine all project Markdown into a single file - Ctrl+Alt+s
3. Generate HTML from this file - Ctrl+Alt+t
4. Make PDF from this file - Ctrl+Alt+p
5. Generate HTML from all project files - Ctrl+Alt+a
6. Make PDF from all project files (export all to a single PDF) - Ctrl+Alt+e
7. Keyboard shortcuts as shown for the functionality listed above

Markdown-It plugins included

Markdown-It plugins included in MarkdownDox:

• markdown-it-abbr
• markdown-it-anchor
• markdown-it-checkbox
• markdown-it-container supporting info, important, danger, caution, warning and note admonitions
• markdown-it-decorate
• markdown-it-deflist
• markdown-it-emoji
• markdown-it-footnote
• markdown-it-ins
• markdown-it-kbd
• markdown-it-mark
• markdown-it-sup
• markdown-it-sub
• markdown-it-table-of-contents
• markdown-it-underline

Sample

A sample of the extended Markdown that these plugins enable can be seen by clicking the link below.

Sample

Requirements

• Visual Studio Code version: 1.30.2 and above.
• A web browser which supports HTML5 with semantic layout elements and flexbox CSS styling
  • Minimum of Chrome 29.0, Edge 11.0, Firefox 22.0, Internet Explorer 10, Opera 48.
• Node.js version 8.9.3 and above.
• Access to the internet to download npm packages.

Recommended extensions

MarkdownDox can be complemented with the extensions listed below to make the task of documentation simpler for you.

• Live Server - launch a local web server and display your output HTML in a web browser with live updates upon file save events.
• Code Spell Checker - spell check your Markdown and your writing.
• Markdown Table Prettifier - cleans up and aligns Markdown table syntax to make it more easily readable.

Installation

Install from Visual Studio Code

Install MarkdownDox from Visual Studio Code:

1. Launch Visual Studio Code and Open the Extensions View from the Activity Bar on the left of the window.

2. Search for the MarkdownDox Extension

3. Click the Install button and let the installation finish

4. Click the Reload button to allow VS Code to load the Extension.

5. In the command prompt window, navigate to the root of the MarkdownDox extension folder:

   • Windows %USERPROFILE%\.vscode\extensions\markdowndox
   • macOS ~/.vscode/extensions/markdowndox
   • Linux ~/.vscode/extensions/markdowndox

6. Type npm install to install the dependency files into the node_modules folder in the extension folder.

Install from a VSIX file

Install the MarkdownDox Visual Studio Code extension from a VSIX file on the command line:

1. Download the VSIX file from the Visual Studio Code Extension Marketplace

2. Open a command prompt and type:

    code --install-extension markdowndox-1.0.0.vsix  
   

3. In the command prompt window, navigate to the root of the MarkdownDox extension folder:

   • Windows %USERPROFILE%\.vscode\extensions\markdowndox
   • macOS ~/.vscode/extensions/markdowndox
   • Linux ~/.vscode/extensions/markdowndox

4. Type npm install to install the dependency files into the node_modules folder in the extension folder.

Extension configuration

MarkdownDox does not have any extension-wide configuration options. All configuration is done at the project level.

Project configuration

Each MarkdownDox documentation project has its own project configuration file titled mdox_config.json.

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.

images_folder: "./images"

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.

stylesheet_folder: "./css"

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.

includes_folder: "./includes"

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 include statement on a line of its own with an empty line before and after it, e.g.:

include::(includes/header.md)

project_output_folder: "./docs"

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.

stylesheet_path: "./css/mdox_default.css"

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.

highlight_stylesheet_path: "./css/default.css"

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.

use_internal_stylesheet: false

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:

<link rel="stylesheet" type="text/css" href="css/mdox_default.css" />

project_files_list:[
"Help.md",
"Sample.md"
]

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.

show_errors_in_output_html: true

If true, when an include file is not found during processing, a message is inserted into the output HTML file - INCLUDE FILE CONTENTS NOT FOUND.

If false, the output HTML file is generated without the missing include content.

auto_include_header_footer_nav: true

If true, the project include files header.md, footer.md and navigation.md are automatically processed and included in the output HTML files, even if they are not explicity included using the include statement in the source Markdown 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 navigation.md file blank.

If false, then only explicitly declared include statements will be processed and included in the output HTML file.

To include header, footer and navigation when this option is set to false, add the include statement on a line of its own with an empty line before and after it, e.g.:

include::(includes/header.md)

insert_page_breaks: true

If true, a page break tag <div class="page" /> is added between each Markdown file processed when the user selects to Combine all project Markdown into a single file or Make PDF from all project files.

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.

pdfProjectFilesList: [
"Help.md",
"Sample.md"
]

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.

PDF options

The options below are passed to the puppeteer library which creates the output PDF file. For information on these settings, please refer to the puppeteer page.pdf([options]) page.

pdfChromeExecutablePath: ""

pdfScale: 1

pdfPaperFormat: "A4"

pdfDisplayHeaderFooter: true

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>"

pdfPrintBackgroundGraphics: true

pdfOrientationLandscape: false

pdfPageRanges: ""

pdfWidth: ""

pdfHeight: ""

pdfMarginTop: "1cm"

pdfMarginRight: ""

pdfMarginBottom: "1cm"

pdfMarginLeft: ""

pdfPreferCSSPageSize: false

Usage

Getting started

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.

Known Issues

None yet. :)

Release Notes

1.0.0

Initial release of MarkdownDox.

---