Markdeep

✒

✒

Markdeep is a technology for writing plain text documents that will look good in any web browser, whether local or remote. It supports diagrams, calendars, equations, and other features as extensions of Markdown syntax.

Markdeep is free and easy to use. It doesn't require a plugin or Internet connection. Your document never leaves your machine and there's nothing to install. Just start writing in your favorite text editor. You don't have to export, compile, or otherwise process your document. Here's an example of a text editor and a browser viewing the same file simultaneously:



📓 × File Edit Format View Help Text Editor View

☐ Example × + × ← → ↻ Web Browser View

Markdeep is ideal for design documents, specifications, README files, code documentation, lab reports, blogs, and technical web pages. Because the source is plain text, Markdeep works well with software development toolchains.

Markdeep was created by Morgan McGuire (Casual Effects) with inspiration from John Gruber's Markdown and Donald Knuth's and Leslie Lamport's LaTeX.

Style Features

Unique features:

Diagrams

Insert documents into one another

LaTeX equation typesetting and numbering

Table of contents

Reference images and embedded images

Document title and subtitle formatting

Schedules and calendars

Section numbering and references

Figure, listing, and table numbering and references

Smart quotes

Embedded video

CSS stylesheets

Page breaks

En dash, em dash, ×, minus, and degrees

Attributes on links

Unindexed sections

Works in any browser by adding one line to the bottom of a text document

Fallback to ASCII in a browser if you have neither the local file nor Internet access

Optionally process server-side with node.js

Optionally batch process to PDF with headless browser flags

HTML export to static content using ?export in the URL or Rasterizer

Tables

Paragraph formatting

Automatic e-mail address and URL linking

Nested, numbered and bulleted lists

Fenced code blocks

Links and reference links

Task lists

Bold, italic, code, strikethrough

Hyperlinks

Attributes on images

Blockquotes

Citations

Footnotes and endnotes

Definition lists

Images

Doesn't italicize math with * or words containing underscores

Unicode

Admonitions (callout notes)

HTML passthrough

Quick-start Templates

starter.md.html Default web template with monospace/"ASCII" fallback slate.md.html Dark mode API documentation style company/whitepaper/company-whitepaper.md.html, company-whitepaper.css, company-logo-256.png, company-background.png Corporate whitepaper template for online viewing and PDF generation. Download all four files and then replace the logos with your own. Matches the Company API template. company/api/company-api.md.html, company-api.css, company-logo-512.png Corporate API template for online viewing. Download all three files and then replace the logo with your own. Matches the Company whitepaper template. journal.md.html For daily project journaling newsmag.md.html A template in the style of a news magazine, with drop caps, multiple subtitles, and modern fonts. website.md.html Simple website example with a left-hand navigation menu and top banner apidoc.md.html API documentation style (by Aras Pranckevičius) latex.md.html LaTeX article formatting with fast load (no flashing). Note that you can use LaTeX math in any Markdeep document. This template is for those who like LaTeX's default style as well. dark.md.html Black background with aggressive styling and fast load (no flashing) slides.md.html Template for generating PDF slideshows. See also Markdeep-slides

Get Started

To create a Markdeep document, just open any text editor and start writing. Paste the following at the bottom of your document as a single line. Then, save it as plain text with a filename with extension .md.html .

<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

If you wish to use Unicode characters in your source document, you must put the following line at the top:

<meta charset="utf-8">

You can drag your document into a web browser or double click on it to see it with formatting. You can also read the document in a browser when you don't have an Internet connection. If you want to avoid losing formatting when offline, just keep markdeep.min.js in the same folder.

View the plain source of the feature demo to learn the formatting styles that you can use. Markdeep extends Markdown, and to quote John Gruber:

The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions.

To inspect the original text source for a Markdeep document in a browser, just add ?noformat to the end of its URL.

Editing Tips

Markdown Modes for Popular Editors

Visual Studio Code provides built-in Markdown support

Visual Studio

Emacs

Vi

Sublime

Notepad++

Atom provides built-in Markdown support; see below for enabling it

For Markdeep + Markdown Atom support, press Ctrl+Alt+P to open the Command Palette. Type "open your config" and then click on the result. This will edit your config.cson file. Add the following entry:

"*": core: customFileTypes: "source.gfm": ["md.html", "md"]

For Markdeep + Markdown Emacs installation, save markdown-mode.el in ~/emacs.d/ and add the following lines to your ~/.emacs file:

;; Uncomment the following line on OS X ;; (add-to-list 'load-path (expand-file-name "~/.emacs.d")) (autoload 'markdown-mode "markdown-mode" "Major mode for editing Markdown" t) (add-to-list 'auto-mode-alist '("\\.md.html\\'" . markdown-mode) (add-to-list 'auto-mode-alist '("\\.md\\'" . markdown-mode))

Diagram Tips

There are a lot of techniques that can make drawing diagrams in plain text easier. I just use Visual Studio or Emacs in overwrite mode, and do everything by hand. I find that much easier than installing or learning a new tool. Here are some basic editor tricks:

In most editors, pressing the insert key will enter overwrite mode, where you can type without inserting. If you're on a Macbook in Bootcamp, press fn + return for insert. Or, in Emacs, use M-x overwrite-mode to toggle overwriting.

for insert. Or, in Emacs, use to toggle overwriting. In Visual Studio, hold down Alt while selecting to make a selection rectangle. This allows you to insert, type, and delete across multiple lines.

In Emacs, you can define a macro on the fly with C-x ( , some key strokes, and then C-x ) . Press C-x e to play back the macro, and keep repeating e to keep executing it. I use this to eliminate the manual work of repetitive actions, for example, adding a space on the left of an object and deleting one on its right to shift the object right.

Overwrite-mode, Artist-mode, or Picture-mode in Emacs. These are minor modes that you can toggle on top of your major (language) mode.

Vim DrawIt!

ASCIIFlow Infinity is a free web tool for drawing ASCII diagrams.

Org-mode is a major mode in Emacs for...everything. Markdeep diagrams are largely compatibile with its ditaa diagram syntax.

Asciio is a standalone tool.

JavE is a standalone diagram tool, but its syntax isn't entirely compatible with Markdeep.

The Unix tool groff has an interpreter for the Pic language, which can be used to generate diagrams from graphs.

graph-easy can convert Dot and other graph languages to ASCII.

Monodraw is an OS X Unicode art editor that can produce Markdeep diagrams, but you should avoid using non-ISO 8859-1 (Latin 1) characters, since they won't produce lines.

art editor that can produce Markdeep diagrams, but you should avoid using non-ISO 8859-1 (Latin 1) characters, since they won't produce lines. FIGlet will convert text to ASCII art banners. Some of its fonts are Markdeep compatible.

Examples

Markdeep is used extensively within the technology industry and academia. Manuals, theses, and even whole books have been written in it. Here are some public examples by myself and my colleagues:

Advanced Applications

URL Arguments

You can add the following arguments to any Markdeep document URL to alter how it is displayed. For example, http://foo.bar/index.md.html?export shows the HTML output.

noformat Attempt to display the original source of the document. Due to web browser limitations, in some cases this will not be 100% accurate to the actual file source. export Make the displayed body HTML source code produced by Markdeep. This is useful for exporting a Markdeep document to HTML if you need to paste it into some context, such as an ePub book or Blog site, that does not allow scripts.

Options

Markdeep looks in the window.markdeepOptions object to determine its behavior. The legal options are:

mode A String that can be: 'markdeep' - the default: process the document as Markdeep

- the default: process the document as Markdeep 'script' - do not modify the document

- do not modify the document 'html' - process the document as HTML with embedded Markdeep nodes

- process the document as HTML with embedded Markdeep nodes 'doxygen' - process special tags in Doxygen documentation lang An Object describing the natural language to use for keywords such as Section and Figure. (If your language is already supported by Markdeep, it is much easier to set this via a <meta lang="..."> tag in the document.) Look at the value of the global variable FRENCH in the source code to see the structure of this Object. tocStyle A String specifying the layout style for the table of contents. Values are: 'auto' - Adjust based on the length of the document. (Default)

- Adjust based on the length of the document. (Default) 'none' - Do not show a table of contents

- Do not show a table of contents 'short' - Show a short table of level-1 headers on a line across the top of the document

- Show a short table of level-1 headers on a line across the top of the document 'medium' - Float a small-font full table of contents to the right of the abstract

- Float a small-font full table of contents to the right of the abstract 'long' - Insert a full table of contents in normal font size as the first section after the abstract scrollThreshold A Number specifying the distance in pixels that the body can be scrolled before the scrolled class should be added to the body element. This is useful for creating CSS styles for web page headers that present differently when the document is first shown versus scrolled down to the contents. The default is 80. definitionStyle A String specifying the layout style for definition lists. Values are: 'auto' - Adjust based on the longest definition in each list. (Default)

- Adjust based on the longest definition in each list. (Default) 'short' - Always format as a table, where definitions are in a column on the left.

- Always format as a table, where definitions are in a column on the left. 'long' - Always format using a hanging indent, where the definitions are under the terms. hideEmptyWeekends A Boolean specifying whether the calendar views from schedule lists should remove weekend days if there are no events on them. The default is true . detectMath A Boolean that defaults to true . If true, when LaTeX math surrounded by $...$ , \(...\) , or \begin{...}...\end{...} is encountered, the MathJax processor is automatically loaded from their CDN. Set to false if you don't use math notation, host MathJax locally and include it using a script tag yourself, or use an alternative math processor. showLabels A Boolean that defaults to false . Display all labels for Figures, Listings, and Tables, as well as URLs for images with captions, the document itself, and links. This is useful when printing proofs of book chapters. sortScheduleLists A Boolean that defaults to true . Sort schedules in order of increasing date, regardless of the order in which events appear in the source document. captionAbove A table mapping diagram , image , listing , and table to Booleans. Each defaults to false , meaning that captions appear below (after) the objects. Set values to true to move the captions above (before) the objects. Example: markdeepOptions.captionAbove.listing = true . In the Markdeep source document, captions must always appear after the object. This option only affects where they appear when the document is viewed. onLoad Function invoked after Markdeep is done processing the document and the DOM is ready. linkAPIDefinitions Boolean that defaults to false . If true, inline code referencing a `variable` or `function()` is linked to a definition list that also uses inline code formatting for that `variable` or `function(args...)`. There must be no space between a function name and the opening paren. Names must be fully qualified. inlineCodeLang String name of a supported syntax highlighting language, such as 'Python' or 'C++' . If set, `inline code` set off in back-ticks is be syntax highlighted using that language. A specific span can be forced to a language by using the HTML syntax, e.g., <code lang=Python>...</code> . Does not affect fenced code blocks. smartQuotes Boolean that defaults to true . If true, double ASCII quotation marks are converted to proper Unicode quotation marks by detecting which side of a word they are on.

Tables

You can use a markdown table generator to produce and edit the source for a table in Markdeep, since Markdeep is a superset of CommonMark markdown.

Markdeep to PDF, EPUB, and HTML

You can of course print Markdeep documents to PDF from your browser manually. Markdeep reformats with some sensitivity to page breaks and printing-specific layout when you do so. To automate the process of generating PDF files from Markdeep, I use Chrome in headless mode. For example:

# OS X:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --headless --print-to-pdf=output.pdf input.md.html



# Windows:

C:\Program\ Files\Google\Chrome\Application\chrome.exe --headless --print-to-pdf=output.pdf input.md.html



# Linux:

google-chrome --headless --print-to-pdf=output.pdf input.md.html

http

https

file

markdeep.min.js

I previously used the wkhtmltopdf program for PDF generation this purpose, but its recent versions do not work very well on OS X.

To force sections to begin new pages when printed or in a PDF, add the following to your Markdeep document:

<style>.md h1, .md .nonumberh1 {page-break-before:always}</style>

Andrew Glassner wrote a detailed guide to converting Markdeep to InDesign, a process which he used for producing his recent machine learning book. InDesign gives you an export path to Kindle and EPUB as well as PDF and other book formats.

Noah Doersing made a neat package for generating books (including theses) using Markdeep.

Under OS X, you can run join.py to concatenate multiple Markdeep PDF chapters for a thesis or book with the single-line command:

"/System/Library/Automator/Combine PDF Pages.action/Contents/Resources/join.py" -o merged-file.pdf file1.pdf file2.pdf ...

The ?export option produces raw HTML export in a browser, which you can then manually copy or save. For automated HTML export, see this guide that uses Firefox and another JavaScript file.

For automated HTML export, see also the node.js solution markdeep-rasterizer by Romain Guy.

Markdeep in HTML Documents

By default, Markdeep passes HTML commands through to the browser. This is for HTML in a primarily Markdeep document. If you have a document that is instead primarily HTML and you want to use Markdeep within it, then load the script with the following code at the end of the document inside of the body tag:

<script>window.markdeepOptions = {mode: 'html'};</script>

<script src="markdeep.min.js"></script>

<markdeep>

<diagram>

You can also use <pre class="markdeep"> and <pre class="diagram"> tags.

Markdeep with Doxygen

One-Time Configuration

Add the following to Doxyfile :

HTML_FOOTER = footer.html

EXAMPLE_PATH = markdeep-dir

ALIASES="copy{1}=\htmlonly <script>document.write('<div style=\'display:none;visibility:hidden;\'>');</script> \endhtmlonly \image html \1

\htmlonly <script>document.write('</div>');</script> \endhtmlonly "

markdeep-dir

Doxyfile

footer.html

<script>window.markdeepOptions = {mode: 'doxygen'};</script>

<script src="markdeep.min.js"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js"></script>

<pre class="markdeep">

<pre class="diagram">

Adding Documentation

To insert pages of full Markdeep documents, without any Doxygen or comment syntax, use the \htmlinclude command. To make Doxygen copy images referenced from your Markdeep documents to your documentation output directory, use the \copy command in any Doxygen file.

For example, to set your documentation main page to be Markdeep embedded within the Doxygen docs and copy architecture.png , make a mainpage.dox that contains:

/** \mainpage

\copy{architecture.png}

\htmlinclude mainpage.md.html */

Javascript API

You can prevent Markdeep from autoformatting a document so that you can use it as a Javascript library by loading it as:

<script>window.markdeepOptions = {mode: 'script'};</script>

<script src="markdeep.min.js"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js"></script>

window.markdeep

function format(src, elementMode)

Converts a String or DOM Element containing Markdeep content into a String of HTML that is returned. The result does not include the Markdeep header (stylesheet and math library script tags) or footer (signature line). The input is not modified. Optional argument elementMode defaults to true, which surpresses page titles and a table of contents. Set elementMode = false if processing a whole document at once. Section captions are unaffected by this argument.



function formatDiagram(str, alignment)

Converts a Markdeep diagram (without the surrounding asterisks) to a String containing SVG HTML that is returned. alignment is an optional String value for the float attribute of the SVG node. It may be 'left' , 'right' , or undefined .



function stylesheet()

Returns the Markdeep default stylesheet used for short documents. Markdeep adds extra spacing around the title when formatting a large document.



Code

Markdeep is open source, so you can directly download and modify the source: markdeep.js. You can send suggestions and patches to me directly at morgan@casual-effects.com.

I don't provide technical support and can't add every feature requested. However, so far I've been able to fix all reported bugs within a week or so and often add features if they are straightforward and well-specified. Fortunately, if I'm unable to add the change that you want, you can just make those changes yourself.

Origin and Credits

I created Markdeep because I was no longer willing to choose between design documents that looked good and those that worked well with programming tools. I liked what Markdown did on web servers, so I used that as a starting point and added more styling features and a way to directly view the documents client side in a browser.

HTML is "markup" that extends plain text with formatting. Unfortunately, the formatting tags often make original document source hard to read and write. This is slow and annoying, especially for those of us who use programming tools for document editing or want formatting in documentation files.

John Gruber invented Markdown to address HTML's editing problems. The name "markdown" conveys styling in the opposite direction of the "markup" tag syntax. Markdown beautifies text without explicit tags, based on common practices from ASCII e-mail and plain-text documents.

"Markdeep" is farther "down" from "markdown" on the autostyling and beautification path. Markdeep combines an easy-to-use and browser-friendly packaging with new unique features such as diagrams. The code includes some of the best previous Javascript document formatting libraries and links to MathJax for equation typesetting.

Markdeep was created by Morgan McGuire. It extends the design and implementation work of:

John Gruber's original Markdown concept and specification

Ben Hollis' Maruku (aka "Github") Markdown dialect specification

Michel Fortin's Extra Markdown dialect specification

Ivan Sagalaev's highlight.js for syntax coloring

Contributors to the above open source projects

License

Copyright 2015-2019, Morgan McGuire All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright (c) 2006, Ivan Sagalaev All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of highlight.js nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Release History

Follow @CasualEffects on Twitter for notification of new incremental features and releases.

Old releases are archived as

https://morgan3d.github.io/markdeep/VERSION/markdeep.min.js

latest

You can report bugs to morgan@casual-effects.com by sending a Markdeep document and what you think is wrong about the way that it appears.