Markdeep

✒
Demo | Features | Get Started | Credits |  License

Markdeep is a technology for writing plain text documents that will look good in any web browser. It supports diagrams, common styling conventions, and equations 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 Vi, Nodepad, Emacs, Visual Studio, Atom, or another 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, 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.

Style Features

(See the demo!)

Unique features:

Plus, best-of-breed Maruku Markdown features:

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{white-space:pre;font-family:monospace}</style><script src="markdeep.min.js"></script><script src="http://casual-effects.com/markdeep/latest/markdeep.min.js"></script>

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.

If you wish to use Unicode characters in your source document, you must put <meta charset="utf-8"> at the top.

Diagram Tips

There are a lot of techniques that can make drawing diagrams in plain text easier. I just Visual Studio or Emacs in overwrite mode, and do everything by hand. I find that pretty quick and 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).

Advanced Applications

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

Options

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

mode
A String that can be:
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.


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 [email protected]. I'm particularly interested in suggestions for ways to significantly reduce the (minified) script size and to avoid accidentally processing attributes of embedded HTML without overly complicating the implementation.

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 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, 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

Starting in November 2015, old releases will be archived as

http://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 [email protected] by sending a Markdeep document and what you think is wrong about the way that it appears.