Markdeep
✒

✒
Demo & Doc | Features | Templates | Get Started | Examples | Advanced | Credits | License

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:

Text Editor View
📓
example.md.html
×
  File   Edit   Format   View   Help
Web Browser View
☐
Example
×
+
×
  ←   →   ↻

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

(See the demo!)

Unique features:

Maruku + github + Admonition + CommonMark Markdown features:

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

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:

Others prefer more sophisticated options: 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).

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

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:
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.
tocDepth
A Number specifying the maximum header depth for the medium and long-form table of contents. 1 means only top level headers. The default is 3.
tocStyle
A String specifying the layout style for the table of contents. Values are:
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:
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
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: 

<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>
This will process <markdeep> tags as Markdeep (which may include embedded diagrams enclosed in asterisks), <diagram> 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 <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 \n \htmlonly <script>document.write('</div>');</script> \endhtmlonly "
where markdeep-dir is the location of your optional Markdeep overview documentation files relative to the Doxyfile. footer.html is your custom footer, which must include the following lines:
<script>window.markdeepOptions = {mode: 'doxygen'};</script>
<script src="markdeep.min.js"></script><script src="https://morgan3d.github.io/markdeep/latest/markdeep.min.js"></script>
Within API documentation, you can use <pre class="markdeep"> and <pre class="diagram"> tags to add Markdeep content. Regular markdown will continue to be processed by Doxygen outside of those tags as well.

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>
This allows you to then manually invoke diagram processing or full Markdeep processing from within your own Javascript programs. Markdeep exports the following members on 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:

License

Markdeep is open source. You may use, extend, and redistribute Markdeep without charge under the terms of the BSD 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.
Markdeep includes highlight.js, so you are also bound by its BSD license: 
      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

For notification of new Markdeep releases and features, follow Morgan on:

Old releases are archived as

https://morgan3d.github.io/markdeep/VERSION/markdeep.min.js
You can modify the Markdeep line at the bottom of a document to hardcode to a specific version instead of the default version of "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.