✒

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:

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.

(See the demo!)

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

Maruku + github + Admonition + CommonMark Markdown features:

• 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

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.

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

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.

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.
• 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.

Others prefer more sophisticated options:

• 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.
• FIGlet will convert text to ASCII art banners. Some of its fonts are Markdeep compatible.

What about the “ASCII drawing characters,” the DOS code page 437
and 850 characters? They’re not widely supported in most modern
monospace fonts (and thus editors), which are keyed to
Unicode. Although Unicode has the same box drawing characters,
they’re now at different code points and not well supported by
text-only tools (alas! I grew up with text-mode graphics and miss them).

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:

• API documentation
• Syllabus
• Game design document
• Homework assignment
• Lecture slides
• Software library website
• Game report
• Blog 1, Blog 2
• Curriculum Vitae (Resume)
• Thesis

The following features are experimental and may change at any
time. See the release history for change information
between versions.

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

The the window.markdeepOptions JavaScript object
determines the behavior of Markeep. The legal options are:

mode

A String that can be:

• 'markdeep' – the default: process the document as Markdeep
• 'script' – do not modify the document
• 'html' – 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 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)
• 'none' – 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
• 'medium' – 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.

autoLinkImages

A Boolean specifying whether images should automatically be hyperlinked
to show that image in a separate tab. The default is true.

definitionStyle

A String specifying the layout style for definition lists. Values are:

• 'auto' – 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.
• '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., .... 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

This will print some error messages but should also create the PDF correctly. The filename can be a raw OS-level filename, a http or
https protocol URL, or a file protocol URL. You may need to
host the markdeep.min.js script in the same directory as your content for
local files, depending on your browser and system configuration.

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:

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:

This will process tags as Markdeep
(which may include embedded diagrams enclosed in
asterisks), tags as Markdeep
diagrams (which do not need enclosing asterisks), and leave any
other content in the document unmodified as HTML.

You can also use

and

tags.

Markdeep with Doxygen

One-Time Configuration

Add the following to Doxyfile: