Markdeep

Demo | 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
×
Web Browser View
Example
×
+
×

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

Markdeep was created by Morgan McGuire at 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:

Plus, Maruku + github + CommonMark Markdown features:

Quick-start Templates

starter.md.html Default web template with monospace/"ASCII" fallback
latex.md.html LaTeX article formatting with fast load (no flashing)
dark.md.html Black background with aggressive styling and fast load (no flashing)
slides.md.html Template for generating PDF slideshows

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"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></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 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

Markdeep looks in the window.markdeepOptions object to determine its behavior. 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.
tocStyle
A String specifying the layout style for the table of contents. 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.


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 or HTML

You can of course print Markdeep documents to PDF from your browser manually. To automate the process of generating PDF files from Markdeep, I recommend wkhtmltopdf, a free, open-source, cross-platform command-line utility. If you include Latex/Mathjax math or remote fonts, ensure that they are loaded before the actual print operation occurs by using a delay. For example:

wkhtmltopdf --dpi 600 --print-media-type --javascript-delay 10000 --no-stop-slow-scripts report.md.html report.pdf
(Due to a limitation of wkhtmltopdf, this doesn't work if you're hosting Markdeep locally.)

wkhtmltopdf has many options for controlling formatting. When batch processing reports, I often add the options --header-spacing 5 --default-header to print the name of the document and page numbers.

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>

Under OS X, you can also 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 ...

For HTML export, see this guide that uses Firefox and another JavaScript file.


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

Set an explicit footer in Doxyfile with:

HTML_FOOTER = footer.html
Include the following lines in the footer.html:
<script>window.markdeepOptions = {mode: 'doxygen'};</script>
<script src="markdeep.min.js"></script>
Use <pre class="markdeep"> and <pre class="diagram"> tags in your documentation.


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>
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. Implementation suggestions and patches are welcome at morgan@casual-effects.com. I'm particularly interested in suggestions for ways to significantly reduce the (minified) script size further.

This was a small hobby project, so 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 few days 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 for 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-2016, 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

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

Old releases are archived as

https://casual-effects.com/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.