A Markdown-to-HTML documentation generator that is feature-rich, customizable, lightweight, and platform-agnostic.
This tool was developed with the intention of being used locally, i.e. md-docs/*.md files compile to html-docs/*.html files, the latter of which can be viewed locally in any browser regardless of device. If you want to see an example of the input/output or learn more about Markdown, open the md-docs/markdown.md and html-docs/markdown.html files and compare them.
My personal use-case employs Resilio Sync to synchronize the contents of html-docs/ to my phone, which ensures I always have access to my documentation on my two primary computing platforms.
Documentation is an invaluable tool in development (and, as I have found, also in life). The goal of this project is as follows:
- To use the elegant simplicity of Markdown to write maintainable, well-formatted documentation;
- To dynamically generate a table-of-contents (TOC) from the document's headings;
- To compile the Markdown file into a responsive, spec-compliant, platform-agnostic HTML document; and
- If desired, to be able to print out documentation and have it be well-formed.
- Prerequisite: Have Node.js installed.
- Download a clone/copy of this repository.
- Open a terminal window at the root of the repository.
- Run
npm installto download all dependencies.
- Make a copy of
md-docs/template.mdand rename it. - Run
npm run gulpto start the tasks. - Open the new file and document until your heart is content.
- Lightweight: All features are written in vanilla JavaScript and run server-side via the
gulptask. The only JavaScript that runs client-side is jquery-smooth-scroll (see below for more details). - Efficient: Only the documentation files that have been modified are run through the task. Courtesy of gulp-changed.
- Table of Contents: Manually trying to maintain TOCs is a headache. This is why Documentastic uses gulp-doctoc to automatically generate a dynamic TOC for you based on the structure of your document's headings.
- Easy to read, easy to write: Reading and writing in Markdown couldn't be simpler... as long as you're at a computer. If you're on a mobile device, why should you download yet another app just to read Markdown files? Documentastic uses gulp-marked to compile your Markdown files into platform-agnostic HTML documents, allowing you to read them in any browser.
- Syntax highlighting: Code syntax highlighting is done server-side within the
gulp-markedtask courtesy of prism.js. - Function or form - why not both?: For best browser compatibility and to avoid nasty surprises, HTML documents should be well-formed and comply with the W3C specification.
- Documentastic keeps your working Markdown file clean and your compiled HTML document compliant by using gulp-inject to inject HTML code partials containing the required
<doctype>,<html>,<head>, and<body>tags.
- Documentastic keeps your working Markdown file clean and your compiled HTML document compliant by using gulp-inject to inject HTML code partials containing the required
- DOM manipulation: Documentastic uses gulp-dom to:
- Set a
titlefor all documents; - Set attributes on external links; and
- Convert Markdown
[x]checkboxes into HTML<input type="checkbox">elements.
- Set a
- Minimal disk space: Compiled HTML code is minified courtesy of gulp-htmlmin.
- Platform-agnostic: Free yourself from the chains of platform dependency and vendor lock-in. As long as you have a browser, you can read your documents.
- Responsive: Documents are responsive and will scale gracefully according to device screen size.
- Stylin': CSS styling courtesy of the GitHub Markdown Stylesheet.
- Smooth moves: Smooth-scrolling is added to all internal links (i.e. everything in the document's TOC) courtesy of jquery-smooth-scroll.
- Printer-friendly: Documents are printer-friendly by default.
Copyright 2017 Dustin Ruetz.