Processing math: 100%

Contents

(Top)
Project page
About
How does it work?
Usage
Changelog
License
Credits
Supported languages
Using stddoc as library
10  Markdeep Feature Demo
11  Basic Formatting
  11.1  Links
  11.2  Lists
  11.3  Definition Lists
  11.4  Schedule Lists
  11.5  Block Quotes
  11.6  Tables
  11.7  Page Breaks
  11.8  Images and Video
  11.9  Symbol Substitutions
  11.10  Admonitions
  11.11  Fenced Code Blocks
    11.11.1  HTML and LaTeX Blocks
    11.11.2  Code Blocks with Captions
    11.11.3  Multi-code Blocks and Custom CSS
    11.11.4  Less-than Signs in Code
  11.12  Diagrams
12  Diagram Examples
  12.1  Lines with Decorations
  12.2  Graph with Large Nodes
  12.3  Graph with Small Nodes
  12.4  Flow Chart
  12.5  Line Ends
  12.6  Trees
  12.7  Circuits
  12.8  Gantt Chart
  12.9  Big Shapes
  12.10  Small Shapes
  12.11  Overlaps and Intersections
  12.12  Big Grids
  12.13  Small Grids
  12.14  Tiny Grids
  12.15  Dot Grids
  12.16  Unicode in Diagram
  12.17  Graphics Diagram
  12.18  Annotated Table Diagram
  12.19  Icon Diagram
  12.20  Styling Diagrams
13  Horizontal Rules
14  Embedded Math
15  ATX Headers
  15.1  H2
    15.1.1  H3
16  Multiple Columns
17  Custom Formatting
  17.1  Manual
  17.2  Style Sheets
    17.2.1  Latex Article
    17.2.2  Dark
    17.2.3  API Documentation
    17.2.4  Presentation Slides
  17.3  Paragraph Numbering
18  Localization
19  Unicode (in UTF-8 encoding)
20  Gravizo Support
21  Including/Inserting Other Documents
22  Differences from Other Markdown
  22.1  Features
  22.2  Temporary Limitations
  22.3  Permanent Limitations

   

Project page

   

About

   

How does it work?

   

Usage

   

Changelog

   

License

   

Credits

   

Supported languages

Language /// comment --- comment ### comment
ActionScript Yes  
Ada Yes  
AngelScript Yes  
AppleScript Yes  
AWK Yes
Bash Yes
Bourne shell Yes
C (C99) Yes  
C shell Yes
C# Yes  
C++ Yes  
ChaiScript Yes  
Cobra Yes
D Yes  
Dao Yes
Eiffel Yes  
Euphoria Yes  
GameMonkey Yes  
GML Yes  
Go Yes  
Haskell Yes  
Java Yes  
JavaScript Yes  
JetScript Yes  
jtc Yes  
Jx9 Yes  
Kotlin Yes  
Lua Yes  
Maple Yes
Neko Yes  
Object Pascal (Delphi) Yes  
Objective-C Yes  
Occam Yes  
Pawn Yes  
Perl Yes
Perl6 Yes
PHP Yes Yes
PowerShell Yes
PSL Yes  
Python Yes
QuakeC Yes  
R Yes
Ruby Yes
Rust Yes  
SASS Yes  
Scala Yes  
Seed7 Yes
SGML Yes  
SGScript Yes  
SPARK Yes  
SQL Yes  
Squirrel Yes  
Swift Yes  
Tcl Yes
Terra Yes  
TSQL Yes  
Vala Yes  
VHDL Yes  
Wren Yes  
Xojo Yes  

   

Using stddoc as library

#include <stdio.h>  // stddoc.c (v1.0.1)
#include <stdlib.h> // - rlyeh, public domain
#include <string.h>
static void stddoc( FILE *in, FILE *out ) {
   fprintf(out, "%s\n", "<meta charset='utf-8' emacsmode='-*- markdown -*-'>");
   fprintf(out, "%s\n", "<link rel='stylesheet' href='https://casual-effects.com/markdeep/latest/apidoc.css?'>");
   fprintf(out, "%s\n", "<style>.backtick, .tilde {overflow-x: auto;} .longTOC {overflow-x: hidden;}</style>");
   struct { int on, prev; } stack[256] = {0}, *quote = stack;
   for( char *buffer = (char *)malloc(16384); buffer; buffer = (free(buffer), 0))
   for( int line = 1; fgets( buffer, 16383, in ) && !feof(in) ; ++line ) {
       const char *tag = strstr(buffer, "//""/");
       tag = tag ? tag : strstr(buffer, "##""#");
       tag = tag ? tag : strstr(buffer, "--""-");
       char next = tag ? *(tag+=3) : 0;
       int markdeep = next == ' ' || next == '\r' || next == '\n', forgot_quote_end = markdeep && ( quote > stack );
       if( next == '!' ) fprintf( stderr, "Warning: (Line %d) %s", line, tag );         // warning comment
       if( next == '>' || forgot_quote_end ) if( quote > stack     ) { --quote, ++tag; if( quote  == stack ) fprintf( out, "%s\n", "~""~~\n"); }
       if( next == '<'                     ) if( quote < stack+255 ) { ++quote, ++tag; fprintf( out, "%s", quote-1 == stack ? "\n~""~~" : "(...)"); }
       if( quote == stack+1 || markdeep ) {
           tag = tag ? tag : buffer;
           fprintf( out, "%s", tag + (tag[0] == ' ') );
       }
   }
   while( quote > stack ) { --quote; fprintf( out, "%s\n", "~""~~\n" ); }
   fprintf(out, "%s\n", "<s""cript>m""arkdeepOptions={tocStyle:'long'};");
   fprintf(out, "%s\n", "<!-- M""arkdeep: --><s""cript src="https://casual-effects.com/m""arkdeep/latest/markdeep.min.js?">");
}
   

Markdeep Feature Demo

Morgan McGuire

This demonstration documents the features of Markdeep and acts as a test for it. Markdeep is a text formatting syntax that extends Markdown, and a Javascript program for making it work in browsers. The two most powerful features are its ability to run in any web browser on the client side and the inclusion of diagrams.

Click here to see this document without automatic formatting.

Markdeep is free and easy to use. It doesn't need a plugin, or Internet connection. There's nothing to install. Just start writing in Vi, Nodepad, Zed, Emacs, Visual Studio, Atom, or another editor! You don't have to export, compile, or otherwise process your document.

If you want to support development of Markdeep, just buy my Graphics Codex book for $10 on Amazon. Revenue from that funds my open source projects.

   

Basic Formatting

Text formatting:

Source Result
**bold** bold
__bold__ bold
*italic* italic
_italic_ italic
~~strikethrough~~ strikethrough
`inline code` inline code
5 kg/m^3 5 kg/m3

You can add CSS to change the styles. See the Custom Formatting section for some examples.

Formatted text may cross lines and be as small as a single character. It can also be indented and split across lines simultaneously.

Markdeep intelligently does not apply bold or italic formatting to math expressions such as x = 3 * y - 2 * z or WORDS_WITH_INTERNAL_UNDERSCORES. It also protects HTML <tags> in code blocks from disappearing.

If you want italics or bold inside of a word, for example in: SCUBA = Self Contained Underwater Breathing Apparatus, then just use HTML <b> and <i> tags—a markdown syntax won't be any more readable in that case.

Exponents only work for positive and negative integers. For arbitrary exponents, use LaTeX notation: $x^y$xy, or HTML tags: x<sup>y</sup> ⇒ xy.

   

Links

There are many forms of implicit and explicit links:

Source Result
[hyperlink](http://casual-effects.com) hyperlink
[hyperlink]("http://casual-effects.com") hyperlink
<http://casual-effects.com> http://casual-effects.com
http://casual-effects.com http://casual-effects.com
morgan@casual-effects.com morgan@casual-effects.com
test@foo.co.uk test@foo.co.uk
<test@foo.co.uk> test@foo.co.uk
Lists section Lists section
Tiny Grids subsection Tiny Grids subsection
Section [Lists] Section 11.2
sec. [lists] sec. 11.2
subsection [lists] subsection 11.2
table [states] table 1
tbl. [states] tbl. 1
Table [states] Table 1
figure [robot] figure 2
fig. [robot] fig. 2
Figure [robot] Figure 2
lst. [sort] lst. 1
listing [sort] listing 1
Listing [sort] Listing 1
[New York Times][nyt] New York Times
[Google][] Google
footnote [^syntax] footnote1
[#Kajiya86] [Kajiya86]

Any section header name followed by “section”, “subsection”, or “sec.” will automatically be linked to that section. To link by number, use one of those key words followed by the section name in brackets. This won't work if you use the actual word “section” as the title of a section...but it would be unexpected to have a section named “section” in a real document anyway.

You can also insert HTML anchor (<a>) tags to create arbitrary internal links.

Reference-style links include arbitrary formatted text in brackets followed by a case-insensitive symbolic name that must be defined elsewhere in the document:

Put the definitions at a convenient location elsewhere in the document:

    [nyt]: http://nytimes.com
    [google]: http://google.com

Markdeep also supports footnotes, endnotes1, and citations [Kajiya86] using a similar syntax. The actual notes and bibliography may be placed at the bottom of the document:

    [#Kajiya86]: James T. Kajiya. 1986 ...

    [^syntax]: Endnotes look like ...

Regular links may also have attributes, for example, this link will directly download.

URLs in explicit links may be surrounded by optional " quotation " marks. If your URL contains parentheses, then it must be surrounded in quotation marks to make it unambigious:

URLs with various forms of special characters are handled well even without quotation marks:

You can also use the CommonMark angle bracket syntax <http://foo.com/bar?arg=value&hello>http://foo.com/bar?arg=value&hello provided that your URL only contains lower-case letters. Otherwise the browser interprets it as a tag and converts it to lowercase before Markdeep runs.

Bibliography:

[ Kajiya86] James T. Kajiya. 1986. The Rendering Equation. In Proceedings of Computer Graphics and Interactive Techniques (SIGGRAPH '86), ACM, 143-150. http://dx.doi.org/10.1145/15922.15902

 1 Endnotes look like reference-style links with an empty text field. Endnotes may not contain multiple paragraphs (sorry, David Foster Wallace), although they may refer to other endnotes.

   

Lists

A blank line or line ending in a colon must precede lists. Lists have lines that begin with a number (which is not required to increment) and a period, or a bullet character (-, *, +). They can also be nested. Example:

1. Monday
2. Tuesday
  1. Morning
  2. Afternoon
3. Wednesday
  - Bullets
  - Bullets
1. Thursday
  + Bullets
  + Bullets
1. Friday
  * Bullets

Examples of lists and floating diagrams: ABCDEFG

  1. Monday
  2. Tuesday
    1. Morning
    2. Afternoon
  3. Wednesday
    • Bullets
    • Bullets
  4. Thursday
  5. Friday

A list with just bullets:

A list containing a code block:

  1. This is the first list item.

    // This is a code block
    if (x > 0) printf("hello!\n");

  2. This is the second list item.

Lists can also:

or

Lists with blank lines between the elements are formatted with more spacing. There's actually nothing special about this...that's just the regular paragraph separator.

  1. Here's a list with some large elements that I chose to format by putting a blank line between the elements to make them more visually distinguished.

  2. That's necessary with paragraph-sized elements; otherwise the text would appear to run together into a wall of text!

    • You can also
    • Nest lists within lists with spaces

Lists that begin with a number other than 1 use that number as the start index. The subsequent numbers are irrelevant and automatically replaced with ascending numbers:

  1. A list that starts at six!
  2. and just
  3. keeps going...

   

Definition Lists

Apple

Pomaceous fruit of plants of the genus Malus in the family Rosaceae.

Multiple paragraphs are supported.

Orange

The fruit of an evergreen tree of the genus Citrus.

  • Can also
  • Put lists
  • In definitions

Definition lists with short definitions are formatted more tersely:

Grapes

Available in purple (“red”) and green (“white”) varieties.

Bananas

Only yellow.

   

Schedule Lists

Schedule lists contain titles that begin with a valid date. After the title, arbitrary indented content appears, including lists, text, and equations:

Tuesday Feb 16, 2016: Project Launch
 - Create specifications
 - Initialize revision control system

Friday Feb 19, 2016: Build Milestone
 - Build system fully functional
 - Placeholder unit tests committed

(Monday Feb 29, 2016): Office Closed

If the schedule is sufficiently long and dense, then a calendar preview is shown before it. Entries in parenthesis with no further details are formatted with a more subtle style.

Formatted schedule lists look like:

February 2016
MondayTuesdayWednesdayThursdayFriday
1   2   3   4   5  
8   9   10   11   12  
15   16Project Launch17   18   19Build Milestone
22   23   24Site Visit25   26Demo Milestone
29Office Closed1 2 3 4 

March 2016
MondayTuesdayWednesdayThursdayFriday
29 1Code Freeze2   3   4  
7Beta8   9   10   11  
14   15   16Gold17   18  
21   22   23   24   25  
28   29   30   31   1 

 Tuesday
16 Feb 2016
Project Launch

  • Create specifications
  • Initialize revision control system

 Friday
19 Feb 2016
Build Milestone

  • Build system fully functional
  • Placeholder unit tests committed

Plan for weekend overtime if we miss this milestone

 Wednesday
24 Feb 2016
Site Visit

Whole team vistits client. Dress appropriately.

 Friday
26 Feb 2016
Demo Milestone

  • Internal demonstrations for management
  • QA reports due

 Tuesday
1 Mar 2016
Code Freeze

  • Commit final features before this date
  • Only priority 1 fixes with issue tracking numbers after this point

 Monday
7 Mar 2016
Beta

 Wednesday
16 Mar 2016
Gold

Dates can be in any unambigous format that includes a month, day, and four-digit year between 1000 and 2999, such as:

The US date format MM/DD/YYYY is not supported because it is ambiguous. The date may include the name of a day of the week (e.g., Sunday). It will be replaced with the correct day.

When months are given by name, they must match the localization settings.

   

Block Quotes

Email-style indenting creates a blockquote:

This is an indented blockquote: Ut at felis diam. Aliquam massa odio, pharetra ut neque sed, commodo dignissim orci. Curabitur quis velit gravida, blandit diam nec, lacinia quam. Maecenas pharetra, velit in vestibulum auctor, diam ipsum suscipit arcu, non sodales orci nibh sit amet leo. Nulla dictum

Blockquotes formatted in the style of an actual quotation receive special treatment for fancy quoting:

You want to make it seem alive and effortless and fun, but that's an art that took me 25 years to really learn. I wanted to do it very much 25 years ago, but I didn't know how. — David O. Russell, director of American Hustle

   

Tables

Source:

 Maine | Iowa | Colorado 
-------|------|----------
   1   |  4   |   10
  ME   |  IA  |   CO
 Blue  | Red  | Brown
  [Optional caption]

 Maine | Iowa | Colorado 
-------|------|----------
   1   |  4   |   10
  ME   |  IA  |   CO
 Blue  | Red  | Brown
[Table [states]: Caption with label.]

Item | Type | Cost
---- |:----:| ----:
Fish |  F   | 1.00
Axe  |  W   | 3.25
Gold |  I   |20.50


 | A |
 |---|
 | B |
 | C |
 | D |

Result:

Maine Iowa Colorado
1 4 10
ME IA CO
Blue Red Brown
Optional caption

 
Maine Iowa Colorado
1 4 10
ME IA CO
Blue Red Brown
Table 1: Caption with label.

With alignment:

Item Type Cost
Fish F 1.00
Axe W 3.25
Gold I 20.50

Single-column:

A
B
C
D

   

Page Breaks

To support other markdown conventions, \pagebreak and \newpage will insert a page break in a document when printed or converted to PDF. You can also use a pattern of a series of five + signs on their own line, which will form a horizontal rule on screen and a new page when printed.


To make top-level section headers also force page breaks, add the following to your document or CSS file:

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

Images and Video

There's no natural way to embed an image into a document that is also readable as plain text. Markdeep follows markdown's somewhat reasonable syntax. The source

![A picture of a robot](robot.jpg)

becomes:

A picture of a robot

Optional labels may be applied:

![Figure [robot]: A picture of a robot](robot.jpg)

 
Figure 2: A picture of a robot

Any text after the URL is used as HTML attributes. If the attributes include width or height specifications, then the image is linked to the original.

![Figure [robot2]: A picture of a robot with a caption larger
than it.](robot.jpg width="150px" border="1")

 
Figure 3: A picture of a robot with a caption larger

Really long captions are justified, not centered. This happens automatically when the caption spans multiple lines. You can also use custom CSS to change the formatting of captions.

Floating robot with a large caption.
If the image is embedded in a paragraph and has a caption, then it floats right and any width specification is propagated to the full captioned image, for example, the image to the right of this paragraph. Use a space as your caption if you want this behavior but don't actually want a visible caption.

You can also just use a raw HTML <img> tag:

<img src="robot.jpg" width="128" border="2">

Captionless images work as well. Source ![](robot.jpg) becomes:

Images are centered if they appear in their own paragraph block and inlined otherwise. Grids of images are recognized and laid out as grids using HTML tables:

1

2

3

4

5

This image has a
long caption

Video file extensions are automatically detected and will embed a small video player:

A video

URLs for Youtube and Vimeo videos will also automatically embed a video player:

State Zero

 
Figure 4: The Boy with a Camera For a Face

URLs for images may be surrounded in optional " quotation " marks. If your URL contains parentheses, then it must be surrounded in quotation marks to make it unambigious.

Recall that URLs are not permitted to contain spaces (by their specification), so to embed a local image whose filename has a space, either rename the file or replace the spaces with %20 in the URL version of the name.

   

Symbol Substitutions

Markdeep converts <->, <==>, ->, -->, <-, <--, ==>, and <== to arrows if they aren't in a code block or latex expression and are surrounded by whitespace. Examples:

Two or three minus signs are converted to an em dash—like that.

An “x” between numbers, such as 1920×1080 or 3 × 4, will be converted to the times symbol.

Negative numbers, such as −5 and minus signs between numbers such as 2 − 1, will have a minus sign instead of a hyphen.

Degrees are reformatted to the degree symbol:

It doesn't reformat the word “degree” when not following digits:

“Smart quotes” are applied for double-quote marks based on position relative to whitespace:

“a” b c

a “b” c

a b “c”

a “b!” c

a “b,” c

a “b”. C

a, “b” c

a—“b”—c

a (“b”) c

“error” ⇒ “correction”

Inch or minute markers such as 3' 9" are not converted. Quotation marks in HTML attributes and in code blocks, e.g., var x = "hello world", are not converted.

   

Admonitions

Admonitions are small break-out boxes with notes, tips, warnings, etc. for the reader. They begin with a title line of a pattern of three exclaimation marks, an optional CSS class, and an optional title. All following lines that are indented at least three spaces are included in the body, which may include multiple paragraphs.

The default stylesheet provides classes for “note” (default), “tip”, “warning”, and “error”. These are case insensitive and ignore any colon after the CSS class. Here are some examples:

!!!
    I'm a note. Don't mind me, I'm just sitting here.

!!! note
    Another note.

!!! Tip
    Close the door on the way out.

!!! WARNING
    I'm a warning, perhaps. *Something might happen!*

!!! ERROR: Seriously
    Watch out, something **bad** could happen.

    This is still more error text.

I'm a note. Don't mind me, I'm just sitting here.

Another note.

Close the door on the way out.

I'm a warning, perhaps. Something might happen!

Seriously

Watch out, something bad could happen.

This is still more error text.

   

Fenced Code Blocks

Set off large blocks of code using equal-length strings of tilde ~ or back-tick ` characters. Each produces a different CSS class so that they can be styled differently.

By default, tilde blocks have lines before and after them and are inset for use as code listings instead of large inline code blocks. Both styles receive syntax coloring and automatic programming language detection.

You can override automatic programming language detection by putting the name of the language immediately following the first fence. You can specify a custom CSS class for a code block by placing its name after the language name.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ C
void insertion_sort(int data[], int length) {
    for (int i = 0; i < length; ++i) {
       ...
    }
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

void insertion_sort(int data[], int length) {
    for (int i = 0; i < length; ++i) {
       ...
    }
}

Alternative back-tick markup:

def insertionSort(data):
    for i in range(0, len(data)):
        j = i;

        while (j > 0) and (data[j] < data[j - 1]):
            temp = data[j]
            data[j] = data[j - 1]
            data[j] = temp
            --j
   

HTML and LaTeX Blocks

You can even have HTML in a code block:

<b>Show this</b> HTML as <i>source</i>,
<code>not code</code>.

LaTeX and other languages that use dollar signs work fine inside code fences:

$ \int_0^1 x^2 dx $

$$$a = $$$e

...and of course, Markdeep inside Markdeep:

- Do not 
- Format
  - this as a **list**!
   

Code Blocks with Captions

Code listings may have captions:

 
def insertionSort(data):
    for i in range(0, len(data)):
        j = i;

        while (j > 0) and (data[j] < data[j - 1]):
            temp = data[j]
            data[j] = data[j - 1]
            data[j] = temp
            --j
Listing 1: An insertion sort

If you don't have a lot of exposition to share, then code blocks can be back to back:

printf("Hello\n");
printf("World\n");
   

Multi-code Blocks and Custom CSS

You can interlace different languages or CSS classes within a single code block, but each is required to specify the language in this case. This is convenient for highighting lines or showing the trace of an interactive session.

An example of a fenced code block with a CSS class:

~~~~~~~~~~~~~~ Python input
>>> x = [1, 2, 3, 4]
>>> [y * 2 for y in x]
~~~~~~~~~~~~~~ none output
[2, 4, 6, 8]
~~~~~~~~~~~~~~ Python input
>>> x + [5]
~~~~~~~~~~~~~~ none output
[1, 2, 3, 4, 5]
~~~~~~~~~~~~~
[This listing combines multiple code blocks to show the input and output of an interactive section.]

And its result:

>>> x = [1, 2, 3, 4] >>> [y * 2 for y in x]
[2, 4, 6, 8]
>>> x + [5]
[1, 2, 3, 4, 5]
[This listing combines multiple code blocks to show the input and output of an interactive section.]

   

Less-than Signs in Code

   

Summary

If you have trouble with less-than signs right next to capitalized letters in code blocks, do one of the following:

You don't need to do this for legal HTML or XML in code blocks.

   

Details

Less-than and greater-than signs are allowed in code blocks (as well as anywhere else in Markdeep), and will be handled correctly if they are followed by a whitespace character.

Likewise, legal HTML and XML are correctly processed as code when in code blocks.

However, because browsers interpret "<" immediately followed by a character as an HTML tag, less-than signs without a following space must be formatted more carefully in shell scripts and languages such as C++ and Java.

If the character following the less-than sign is lower-case, for example in: "std::vector<int>", then no consideration is needed. If the character following less-than is a capital letter, then the browser will automatically make it lower case. If the following character is a slash, then the browser will interpret it as a stray tag and automatically remove it.

If you care most about being able to read your document in a browser when the markdeep.js script is not available (due to no local copy and no Internet connection), then either use surrounding whitespace or use HTML entity codes to avoid incorrect processing of less-than signs.

Reformatted Examples:

#include <foo.h>
ls < /dev/null
ls&lt;/dev/null
std::vector< Capitalized > array;
std::vector&lt;Capitalized&gt; array;

If care more about not having to reformat your code examples, then just include them in preformatted <script> blocks:

Script Block Examples:

#include <foo.h>
std::vector<Capitalized> array;
ls</dev/null

You can also include your entire document in a preformatted script block to avoid the need for marking up each code (and inline code) example.

   

Diagrams

ServerDATACYCLESecurityFilePolicyManager Diagrams can be inserted alongside, as in this example, or between paragraphs of text as shown below.

The diagram parser leaves symbols used as labels unmodified, so characters like > and ( can appear inside of the diagram. In fact, any plain text may appear in the diagram. In addition to labels, any un-beautified text will remain in place for use as ASCII art. Thus, the diagram is rarely distored by the beautification process.

  ABoxRoundMixedRoundedDiagonals&SquareCornersSearchInteriorDiaglineif(a>b)Curvedlineobj->fcn()Done?JoinCurvedVertical3not:line'quotes'A||B*bold*NotadotAdash--isnotalineNor/isthis.

Figure 1: Diagrams can also have captions

Code with line-like symbols is allowed in diagrams and is parsed correctly so long as you make it unambiguous:

--x;x->y0__proto____FILE__<=a|bfooy--;x||ya+b

Here's a diagram on the left of some text:

Song of Myself: 35

Would you hear of an old-time sea-fight?
Would you learn who won by the light of the moon and stars?
List to the yarn, as my grandmother's father the sailor told it to me.

Walt Whitman

If there is no leading text on the left except for whitespace, a diagram may omit the asterisks on the right side for convenience:

   

Diagram Examples

   

Lines with Decorations

||

   

Graph with Large Nodes

A12483B5C67D

   

Graph with Small Nodes

A12483B5C67D

   

Flow Chart

STARTABCOMPLEXENDCHOICEPREPARATIONXPROCESSINPUTPROCESSPROCESSX

   

Line Ends

Tests for some tough cases:

   

Trees

111222333123412341234444

   

Circuits

ABYC

   

Gantt Chart

PreproductionAlphaRC1StoryConceptArtModelingRiggingMechanicsEngineCodeGameCodeFreeze

   

Big Shapes

   

Small Shapes

   

Overlaps and Intersections

   

Big Grids

BABABA

   

Small Grids

bbababaa

   

Tiny Grids

   

Dot Grids

··································

   

Unicode in Diagram

x𝚺xt²dt

   

Graphics Diagram

03PEye+y)Reflection12v0v347-+xXRefraction56+zv1v2

   

Annotated Table Diagram

AAABasis16491-210X8520140-1

   

Icon Diagram

ServerCloudDatabaseInternetWiFiBluetooth####LANWindowsOSXiOSUbuntuUbuntu//\\//\\Laptop1Laptop2Tablet1DedicatedServerRack

   

Styling Diagrams

You can use CSS to style all diagrams or individual diagrams. For example, the following has light lines on a dark background:

   

Horizontal Rules

Following the CommonMark specification, any of these patterns can be used (and extended across a whole line, of course) to produce a horizontal rule:

-----

- - -

_____

_ _ _

*****

* * *

Example:







   

Embedded Math

Markdeep automatically includes MathJax if your document contains equations and you have an Internet connection. That means you get the full power of LaTeX, TeX, MathML, and AsciiMath notation. Just put math inside single or double dollar signs.

Lo(X,ˆωo)=Le(X,ˆωo)+ΩLi(X,ˆωi) fX(ˆωi,ˆωo) |ˆnˆωi| dˆωi

You can also use LaTeX equation syntax directly to obtain numbered equations:

eiπ+1=0

A1b=x

If you don't have equations in your document, then Markdeep won't connect to the MathJax server. Either way, it runs MathJax after processing the rest of the document, so there is no delay.

Markdeep is smart enough to distinguish non-math use of dollar signs, such as $2.00 and $4.00, US$5, and 3$. Inline math requires consistent spaces (or punctuation) either outside or inside of the LaTeX dollar signs to distinguish them from regular text usage. Thus, the following all work:

Unless you've changed out the default MathJax processor, you can define your own LaTeX macros by executing \newcommand within dollar signs, just as you would in LaTeX. Markdeep provides a handful of commands defined this way by default because they're things that I frequently need:

Code Symbol
\O(n) O(n)
\mathbf{M}^\T MT
45\degrees 45
x \in \Real xR
x \in \Integer xZ
x \in \Boolean xB
x \in \Complex xC
\n ˆn
\w ˆω
\wo ˆωo
\wi ˆωi
\wh ˆωh
\Li Li
\Lo Lo
\Lr Lr
\Le Le
10\un{m/s^2} 10m/s2

   

ATX Headers

In addition to the underlined headers, you can also use ATX-style headers, with multiple # signs:

   

H2

   

H3

   

H4

   
H5
   
H6

Although: do you really need six levels of subsection nesting?!

You can also create unnumbered sections that will not appear in the table of contents using parentheses around the pound signs:

Unnumbered H2
   

Multiple Columns

You can use the CSS columns style to make an HTML multicolumn block. Then, just use regular Markdeep within it and the browser will automatically apply your multicolumn layout.

Browsers are even smart enough to break the columns correctly when printing to PDF or to a printer. However, for a long document, multiple columns don't work well when displayed on screen. That's because there are no discrete “pages” on screen to break columns. So, the browser will make each column as long as the entire document, which is probably not what you want.

So, multi-column only works well if you know that you have very short sections (as in this example), or if you were planning on printing to separate pages when done.

   

Custom Formatting

   

Manual

Markdeep uses CSS for styling. That means you can embed a style sheet to override anything thatn you don't like about the built-in styling. For example, if you don't want section numbering, just use:

<style>h1:before, h2:before { content: none; }</style>

Markdeep uses Markdown's syntax, even where I disagree with the choices. But you aren't stuck with that. Do you wish that Markdown had specified single-asterisk for *bold*? You can have that:

<style>em.asterisk { font-style: normal; font-weight: bold; }</style>

Each of the list bullets (+, -, *) has its own CSS class. You can use this, for example, to make + entries bold and - ones use a circle:

<style>
  li.plus { font-weight: bold; } 
  li.minus { list-style-type: circle;}
</style>
   

Style Sheets

   

Latex Article

To match the default Latex article formatting, insert the following anywhere in your document:

<link rel="stylesheet" href="https://casual-effects.com/markdeep/latest/latex.css?">

   

Dark

For an aggressively-stylized document with a black background, insert the following anywhere in your document:

<link rel="stylesheet" href="https://casual-effects.com/markdeep/latest/dark.css?">

   

API Documentation

To use the API documentation template, insert the following anywhere in your document:

<link rel="stylesheet" href="https://casual-effects.com/markdeep/latest/apidoc.css?">

   

Presentation Slides

To create presentation slides as a PDF, insert the following into your document, using first-level headers for sections and second-level headers for slides:

<link rel="stylesheet" href="https://casual-effects.com/markdeep/latest/slides.css?">

Then, print the document to PDF.

   

Paragraph Numbering

Academic article or book proofs often have line numbers so that reviewers and editors can refer to specific passages. This doesn't make sense for a document in a browser because line breaks change based on the reader's screen size.

You can add paragraph numbers to your Markdeep document by including the following HTML at the bottom of your document. You can remove the <style> tag and place the code in a CSS file as well.

<style>
p::before {
  content: "¶ " counter(paragraph);
  counter-increment: paragraph;
  margin-left: -50px;
  width: 50px;
  height: 0px;
  overflow: visible;
  font-size: 70%;
  display: block;
  color: #666;
}
</style>
   

Localization

There are two ways to localize the keywords such as Table, Diagram, Monday, etc., from English to your favorite language.

The first is to put a meta tag with a lang attribute in the document, such as <meta lang="ru" charset="utf-8">. If your favorite language isn't supported by Markdeep, just e-mail me a Javascript snippet with the appropriate translations and I'll add it (see the source code for examples).

The second method is to manually set the markdeepOptions.lang field before you include the script in your document.

   

Unicode (in UTF-8 encoding)

To support Unicode input, you must add <meta charset="utf-8"> to the top of your document (in the first 512 bytes).

   

Gravizo Support

Markdeep diagrams have no dependency on third parties or the network (you can store the markdeep.min.js file locally on your machine!) and look the same in your document as on screen in the final document.

If you need the full power of DOT/GraphViz automated layout graphs and can accept a network and third party dependency, you can embed Gravizo within a Markdeep document using either direct Markdeep image syntax or an embedded HTML img tag:

<img src="http://g.gravizo.com/g?digraph G { A -> B -> C; A -> C; }">

![](http://g.gravizo.com/g?digraph G { A -> B -> C; A -> C; })

Markdeep also allows captions on Gravizo graphs and newlines within the URL itself:

 
Figure 5: A more complex graph example

   

Including/Inserting Other Documents

Markdeep currently contains experimental (i.e., beta, may-not-be-supported-in-the-future) support for including one document within another. This is convenient for bibliographies, boilerplate footers and headers, and styling. The syntax is:

(insert otherdocument.md.html here)

The inserted document must be a standalone Markdeep document, including the Markdeep line. It can have any file extension, although .html is recommended and there must be a period in the filename to disambiguate it versus arbitrary TODO-style notes.

The included document will be inserted inline, meaning that footnotes, figure numbering, and other kinds of references will flow correctly. Recursive inclusion is allowed. All paths in an included document are relative to the original document. That's undesirable, and a future release may be able to make those paths absolute.

Here would be an example of embedding example.md.html into current document:

(insert example.md.html here)

   

Differences from Other Markdown

   

Features

There are many, inconsistent markdown variants. Markdeep intentionally differs from a few of them in specific ways:

   

Temporary Limitations

Future releases likely will address these known bugs, limitations, and “missing features”:

   

Permanent Limitations

Due to the special protection from formatting that Markdeep affords <pre> and <code> tags that appear in the document, you cannot nest a code tag inside of another code tag, and likewise for pre tags. Fortunately, it is pretty hard to imagine a case where you would want nested code tags.

formatted by Markdeep 1.18