**Markdeep Documentation and Feature Demo** Morgan McGuire This demonstration documents the features of [Markdeep](http://casual-effects.com/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](https://casual-effects.com/markdeep/features.md.html?noformat) 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. Basic Formatting ======================================================================================= Text formatting: Source | Result -----------------------------------------|------------------------------ `**bold**` | **bold** `__bold__` | __bold__ `*italic*` | *italic* `_italic_` | _italic_ `~~strikethrough~~` | ~~strikethrough~~ `inline code` | `inline code` <code lang=C++>if (inlinedHighlight == "yes") {</code> | if (inlinedHighlight == "yes") { `[news](https://cbc.ca)` | [news](https://cbc.ca) `https://casual-effects.com` | https://casual-effects.com `morgan@casual-effects.com` | morgan@casual-effects.com `5 kg/m^3` | 5 kg/m^3 `5 degrees` | 5 degrees `xbelow` | xbelow `size` | size `size` | size 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 `` 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 `` and `` 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$` ==> $x^y$, or HTML tags: `xy` ==> xy. Links --------------------------------------------------------------------------------------- There are many forms of implicit and explicit links: Source | Result -------------------------------------------|--------------------------------------------- `[hyperlink](http://casual-effects.com)` | [hyperlink](http://casual-effects.com) `[hyperlink]("http://casual-effects.com")` | [hyperlink]("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 `` | `Lists section` | Lists section `Tiny Grids subsection` | Tiny Grids subsection `Section Lists` | Section Lists `Subsection Lists` | Subsection Lists `Section [lists]` | Section [lists] `sec. [lists]` | sec. [lists] `subsection [lists]` | subsection [lists] `table [states]` | table [states] `tbl. [states]` | tbl. [states] `Table [states]` | Table [states] `figure [robot]` | figure [robot] `fig. [robot]` | fig. [robot] `Figure [robot]` | Figure [robot] `lst. [sort]` | lst. [sort] `listing [sort]` | listing [sort] `Listing [sort]` | Listing [sort] `[New York Times][nyt]` | [New York Times][nyt] `[Google][]` | [Google][] `footnote [^syntax]` | footnote [^syntax] `[#Kajiya86]` | [#Kajiya86] `foo()` | `foo()` Any section header name followed by "section", "subsection", or "sec." will automatically be linked to that section. (The keyword "chapter" currently works but is unsupported and likely to change to work differently with multi-file documents in the future.) 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 (``) tags to create arbitrary internal links. When linking to a Markdeep document from another document, you can refer to sections based on either a mangled version of their name or a fully-qualified version of that. The mangling is URI encoding of the section name with spaces removed, in all lowercase. For example, this section can be linked to as `features.md.html#links` or `features.md.html#basicformatting/links`. **The easiest way to generate a link to a section is to simply right-click (or ctrl-click) on that section header in the browser. This will bring up a context menu that allows you to copy either the internal Markdeep text of the link or the external HTML code link.** While a hover would be more discoverable, I chose to use the context menu so that this functionality would work well on touch screens, be easier to style for themes, and not affect layout. Reference-style links include arbitrary formatted text in brackets followed by a case-insensitive symbolic name that must be defined elsewhere in the document: - Example using a symbolic name: [New York Times][nyt] - Example using the text as its own symbol: [Google][] Put the definitions at a convenient location elsewhere in the document: ~~~~~~~~~~~~ none [nyt]: http://nytimes.com [google]: http://google.com ~~~~~~~~~~~~ Markdeep also supports footnotes, endnotes [^syntax], and citations [#Kajiya86] using a similar syntax. The actual notes and bibliography may be placed at the bottom of the document: ~~~~~~~~~~~~~~~~none [#Kajiya86]: James T. Kajiya. 1986 ... [^syntax]: Endnotes look like ... ~~~~~~~~~~~~~~~~ Multiple citations (but not footnotes) may be included within brackets: ~~~~~~~~~~~~~~~~~~none ...the early Monte Carlo rendering methods [#Cook84, #Kajiya86]. ~~~~~~~~~~~~~~~~~~ API links are automatically created from standalone inline code references to functions, arrays, and variables when a definition list exists that provides code-formatted definitions of those entities using backticks. For example: `foo(x, y)` : Returns the foo of `x` and `y` `gamepad_array[]` : Array of all gamepads on this computer A reference to `foo()` is then automatically linked back to its definition. In the case of overloaded definitions, automatic links will always point to the first one. Subsequent definitions are given unique hash URLs that can be explicitly linked. Regular links may also have attributes, for example, [this link will directly download](http://casual-effects.com/markdeep/robot.jpg 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: - [a link with parens]("http://casual-effects.com(bar)") - []("http://casual-effects.com(bar)") URLs with various forms of special characters are handled well even without quotation marks: - [hyperlinks to URLs with underscores](https://archive.org/stream/Bazin_Andre_What_Is_Cinema_Volume_1/Bazin_Andre_What_Is_Cinema_Volume_1_djvu.txt) - https://archive.org/stream/Bazin_Andre_What_Is_Cinema_Volume_1/Bazin_Andre_What_Is_Cinema_Volume_1_djvu.txt You can also use the CommonMark angle bracket syntax `` ==> 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 [^syntax]: 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. [nyt]: http://nytimes.com [google]: http://google.com 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: ***************************** 1. Monday * A B C * 2. Tuesday * *-------->o<------->o * 1. Morning * ^ / ^ | * 2. Afternoon * | v \ v * 3. Wednesday * o----->o---->o<---->* * - Bullets * D E F G * - Bullets ***************************** 4. Thursday 5. Friday A list with just bullets: - Bread - Fish - Milk - Cheese A list containing a code block: 1. This is the first list item. ~~~~~~ // This is a code block if (x > 0) printf("hello!\n"); ~~~~~~ 1. This is the second list item. - Level 1 - Level 2 - Level 3 - Level 1 again - 1 - 1.a - 1.a.i - 1.a.ii - 1.b Lists can also: * Use asterisks * Instead of * Minus signs * `or have code` * *and* other formatting or + Use plus + Signs 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: 6. A list that starts at six! 1. and just 1. keeps going... Task Lists ------------------------------------------------------------------------------ You can use the strikethrough syntax for task lists: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. ~~completed~~ 1. ~~subtask~~ 1. uncompleted ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ which will format as: 1. ~~completed~~ 1. ~~subtask~~ 1. uncompleted or, use github or streamlined checkbox syntax for task lists : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ github: - [x] completed - [x] subtask - [ ] uncompleted streamlined: [x] completed [x] subtask [ ] uncompleted ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ github: - [x] completed - [x] subtask - [ ] uncompleted streamlined: [x] completed [x] subtask [ ] uncompleted 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: ~~~~~~~~~~~~none 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: 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 _Plan for weekend overtime if we miss this milestone_ Wednesday Feb 24, 2016: Site Visit **Whole team vistits client**. Dress appropriately. Friday Feb 26, 2016: Demo Milestone - Internal demonstrations for management - QA reports due (Monday Feb 29, 2016): Office Closed Tuesday Mar 1, 2016: Code Freeze - Commit final features before this date - Only priority 1 fixes with issue tracking numbers after this point Monday Mar 7, 2016: Beta Wednesday Mar 16, 2016: Gold Dates can be in any unambigous format that includes a month, day, and four-digit year between 1000 and 2999, such as: - 2001-03-01 - 1 Apr. 1999 - 4-07-1976 - February 16, 2016 - 2020 Jan. 15 - May 15th, 1982 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: ~~~~~~~~~~~~none 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 [states]: 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 ------------------------------------------------------------------------------ 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](robot.jpg) Optional labels may be applied: ` ![Figure [robot]: A picture of a robot](robot.jpg)` ![Figure [robot]: A picture of a robot](robot.jpg) Any text after the URL is used as HTML attributes. The image is also linked to the original to make flip comparisons and zooming easier in separate tabs. Use the `autoLinkImages: false` setting on `markdeepOptions` to prevent this. ```` ![Figure [robot2]: A picture of a robot with a caption larger than it.](robot.jpg width="150px" border="1") ```` ![Figure [robot2]: A picture of a robot with a caption larger than it.](robot.jpg width="150px" border="1") ![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. Limit captions to three newlines in the source.](robot.jpg width="150px" border="1") ![Captions may contain [links](https://casual-effects.com), but not other images.](robot.jpg width="150px" border="1") ![Floating robot with a large caption.](robot.jpg width="20%") 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 `` tag: ` ` Captionless images work as well. Source `![](robot.jpg)` becomes: ![](robot.jpg) 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](robot.jpg width=100) ![2](robot.jpg width=100) ![3](robot.jpg width=100) ![4](robot.jpg width=100) ![5](robot.jpg width=100) ![This image has a
long caption](robot.jpg width=100) Images may be shown pixel-perfect under zoom (which is good for computer graphics/computer vision results and pixel art) by attaching the `pixel` CSS class: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![Pixel perfect image](invader.png width=150px class=pixel) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![Pixel perfect image](invader.png width=150px class=pixel) Images may have an attribution overlaid, for example, to display copyright information. Use `attrib` and `attrib-url` properties for this: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![](rigging.jpg attrib="Image by Richard Revel, CC0" attrib-url="https://www.publicdomainpictures.net/en/view-image.php?image=192418") ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![](rigging.jpg attrib="Image by Richard Revel, CC0" attrib-url=https://www.publicdomainpictures.net/en/view-image.php?image=192418) Reference Images ---------------------------------------------------------------- Markdeep introduces a new feature called "reference images". These have several nice properties: * Put long image URLs elsewhere in the document for clarity * Indirection so that multiple images can reference a symbolic URL * Embed [base64 encoded images as data URIs](https://www.base64-image.de/) directly in a Markdeep text file ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![This is a base64 embedded reference image][hasselhoff.png] [hasselhoff.png]: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![This is a base64 embedded reference image][hasselhoff.png] The syntax is the same as CommonMark reference _links_, just with square brackets. You can use all of the Markdeep image features with reference images, including image grids, floating images, and images with attributes. [hasselhoff.png]: data:image/png;base64,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 Videos ---------------------------------------------------------------- Video file extensions are automatically detected and will embed a small video player: ![A video](rocket.mp4) URLs for Youtube and Vimeo videos will also automatically embed a video player: ![State Zero](https://www.youtube.com/watch?v=QgPMyvZMBY0) ![Laser Capsize](https://youtu.be/B0RbhyMd3kA?si=aMgCAK9GWUa4hrqI&t=30) ![Figure [fig:boy]: The Boy with a Camera For a Face](https://vimeo.com/channels/staffpicks/151493973) 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. Audio ------------------------------------------------------------------------------ MP3, WAV, OGG, etc. audio for music and podcasts are supported using the same syntax as for images and video: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![The Personal Best CBC Podcast](https://podcast-a.akamaihd.net/mp3/podcasts/personalbest-GRHHTnR3-20180415.mp3) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Creates: ![The Personal Best CBC Podcast](https://podcast-a.akamaihd.net/mp3/podcasts/personalbest-GRHHTnR3-20180415.mp3) Symbol Substitutions ------------------------------------------------------------------------------ Markdeep converts `<->`, `<==>`, `->`, `-->`, `<-`, `<--`, `==>`, and `<==` to arrows if they aren't in a code block or latex expression and are surrounded by whitespace. Examples: - if this ==> then that - here <== there - this <==> that - A <- B - X -> Y - back <-> forth - long --> way - back <-- there Two or three minus signs are converted to an em dash--like that. An "x" between numbers, such as 1920x1080 or 3 x 4 x 6, 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: - Cold, 37-degree F water. - A 45-degree angle. - A right angle's measure is 90 degrees. It doesn't reformat the word "degree" when not following digits: - Don't give me the third degree! - I have two degrees from MIT. "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: ````````````````````````````````````````````````````````````` none !!! 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. !!! 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. Code Blocks ------------------------------------------------------------------------------ Inline code is between backticks. It is not syntax highlighted because it is usually too short to autodetect the language. Use `markdeepOptions = {inlineCodeLang: 'language'"}` in a `script` tag to select a syntax highlighting language from the list below for inline code. 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. The supported languages are (capitalization ignored): `bash cs C# cpp C++ css coffeescript html XML http JSON java Jlia JavaScript Makefile` `markdown objectivec Objective-C PHP perl python PyxlScript ruby shell armasm glsl` `go haskell kotlin lisp lua matlab R rust scheme swift sml tex typescript yaml none` 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) {
       ...
    }
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ C 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: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Show this HTML as source, not code. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `` ````````` ````````` !!! WARNING Please refer to Section [Less-than Signs in Code] for best practices regarding the use of < and >. We recommend wrapping the whole code block in script type="preformatted".../script if you run into any unexpected issues. 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: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python 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 [sort]: 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"); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ### Line Numbers Adding the `linenumbers` CSS class to a listing makes line numbers appear: 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python linenumbers
def insertionSort(data):
...
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python linenumbers 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 [sort2]: An insertion sort with line numbers] ### 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 and custom styling: 
style
.md code > .input  { font-style: italic; }
.md code > .output { font-weight: bold; background: #FF7; margin-left: -20px; padding-left: 20px}
/style

~~~~~~~~~~~~~~ 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: ~~~~~~~~~~~~~~ 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.] ### Less-than Signs in Code ### #### Summary #### Less-than and greater-than signs (`<` and `>`) do not need to be escaped in diagrams or code as long as they do not appear immediately adjacent to a letter. Usually adding spaces or using inline code backquote escaping will suffice even in those cases. If you have trouble with less-than and greater-than signs right next to capitalized letters in code blocks, do _one_ of the following: - Put spaces after angle brackets: `std::vector< Capitalized >` - Use HTML entity escapes: `std::vector&ltCapitalized&gt` - Wrap code examples in script type="preformatted".../script - Wrap your whole document in script type="preformatted".../script 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 you care more about not having to reformat your code examples, then just include them in preformatted `<script>` blocks: **Script Block Examples:** 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 -------------------------------------------------------------------------------- Diagrams can be inserted alongside, as in this **************************** example, or between paragraphs of text as shown * .---------. * below. * | Server |<------. * * '----+----' | * The diagram parser leaves symbols used as labels * | | * unmodified, so characters like > and ( can appear * | DATA CYCLE | * inside of the diagram. In fact, any plain text * v | * may appear in the diagram. In addition to labels, * .-------. .----+----. * any un-beautified text will remain in place for * | Security| | File | * use as ASCII art. Thus, the diagram is rarely * | Policy +->| Manager | * distored by the beautification process. * '-------' '---------' * **************************** ************************************************************************************************* *.-------------------. ^ .---. * *| A Box |__.--.__ __.--> | | | * *| | '--' v | | * *'-------------------' | | * * Round *---(-. | * * .-----------------. .-------. .----------. .-------. | | | * * | Mixed Rounded | | | / Diagonals \ | | | | | | * * | & Square Corners | '--. .--' / \ |---+---| '-)-' .--------. * * '--+------------+-' .--. | '-------+--------' | | | | / Search / * * | | | | '---. | '-------' | '-+------' * * |<---------->| | | | v Interior | ^ * * ' <---' '----' .-----------. ---. .--- v | * * .------------------. Diag line | .-------. +---. \ / . | * * | if (a > b) +---. .--->| | | | | Curved line \ / / \ | * * | obj->fcn() | \ / | '-------' |<--' + / \ | * * '------------------' '--' '--+--------' .--. .--. | .-. +Done?+-' * * .---+-----. | ^ |\ | | /| .--+ | | \ / * * | | | Join | | Curved | \| |/ | | \ | \ / * * | | +----> | '-' Vertical '--' '--' '-- '--' + .---. * * '---+-----' | | | 3 | * * v not:line 'quotes' .-' '---' * * .---+--------. / A || B *bold* | ^ * * | Not a dot | <---+---<-- A dash--is not a line v | * * '---------+--' / Nor/is this. --- * ************************************************************************************************* [Figure [diagram]: 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->y |__| | * | 0 __proto__ __FILE__ <= | * | __ a | b --> foo | * | |__| y--; x || y a + b <--o--+ * |__|__|_______________________________| ********************************************** 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?
* v | * 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: **************************************** * .----. * | | * '----' .------------> * | * '------------- **************************************** Below are some more examples of diagrams. Diagram Examples ================================================================================ Lines with Decorations -------------------------------------------------------------------------------- ************************************************************************************************* * ________ o * * .--------------. * * *---+---. | | o o | ^ \ / | .----------. | * * | | '--* -+- | | v / \ / | | <------. | | * * | '-----> .---(---' --->*<--- / .+->*<--o----' | | | | | * * <--' ^ ^ | | | | | ^ \ | '--------' | | * * \/ *-----' o |<----->| '-----' |__| v '------------' | * * /\ *---------------' * * ◌------○ ◍------● * ************************************************************************************************* Graph with Large Nodes -------------------------------------------------------------------------------- ************************************************************************************************* * * * .---. .-. .-. .-. .-. * * | A +----->| 1 +<---->| 2 |<----+ 4 +------------------. | 8 | * * '---' '-' '+' '-' | '-' * * | ^ | ^ * * v | v | * * .-. .-+-. .-. .-+-. .-. .+. .---. * * | 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D | * * '-' '---' '-' '---' '-' '-' '---' * ************************************************************************************************* Graph with Small Nodes -------------------------------------------------------------------------------- ************************************************************************************************* * A 1 2 4 8 * * *----->o<---->o<----o-----------. o * * ^ ^ | ^ * * | | | | * * v | v | * * o<--->*<---->o---->*---->o---->o<---->* * * 3 B 5 C 6 7 D * ************************************************************************************************* Flow Chart -------------------------------------------------------------------------------- ************************************************************************************************* * . * * .---------. / \ * * | START | / \ .-+-------+-. ___________ * * '----+----' .-------. A / \ B | |COMPLEX| | / \ .-. * * | | END |<-----+CHOICE +----->| | | +--->+ PREPARATION +--->| X | * * v '-------' \ / | |PROCESS| | \___________/ '-' * * .---------. \ / '-+---+---+-' * * / INPUT / \ / * * '-----+---' ' * * | ^ * * v | * * .-----------. .-----+-----. .-. * * | PROCESS +---------------->| PROCESS |<------+ X | * * '-----------' '-----------' '-' * ************************************************************************************************* Line Ends -------------------------------------------------------------------------------- ************************************************************************************************* * * * o--o *--o / / * o o o o o * * * * o o o o * * * * o o o o * * * * * * o--* *--* v v ^ ^ | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / / * * o--> *--> * o / / o * v ' o * v ' o * v \ o * v \ o * v / o * v / * * o--- *--- * * ^ ^ ^ ^ . . . . ^ ^ ^ ^ \ \ \ \ ^ ^ ^ ^ / / / / * * | | * o \ \ * o | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / / * * v v ^ ^ v v ^ ^ o * v ' o * v ' o * v \ o * v \ o * v / o * v / * * * o | | * o \ \ * * * * <--o <--* <--> <--- ---o ---* ---> ---- *<-- o<-- -->o -->* * * * ************************************************************************************************* Tests for some tough cases: ************************************************ * +-+ \ \ | / / * * + + \ v v v / * * +-+ \ .---------. / \ | / * * v| |v vvv * * +-+ --->| |<--- -->o<-- * * | | ^| |^ ^^^ * * +-+ / '---------' \ / | \ * * / ^ ^ ^ \ * * / / | \ \ * ************************************************ Trees -------------------------------------------------------------------------------- ************************************************************************************************* * * * . . . .--- 1 .-- 1 / 1 * * / \ | | .---+ .-+ + * * / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 * * + + | | | | ---+ ---+ + * * / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 * * / \ / \ | | | | | | | | '---+ '-+ + * * 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 * * * ************************************************************************************************* ******************************** * * * X Y * * / \ / \ * * / \ / \ * * A Y --> X C * * / \ / \ * * / \ / \ * * B C A B * * * ******************************** ********************************** * .-. .-. * | X | | Y | * +-+ +-+ * / \ / \ * .+. .+. .+. .+. *| A | | Y | --> | X | | C | * '-' +-+ +-+ '-' * / \ / \ * .+. .+. .+. .+. * | B | | C | | A | | B | * '-' '-' '-' '-' ********************************** Digital Circuits -------------------------------------------------------------------------------- ************************************************************************************************* * ____ * * * | |_____.---. | * * o _____| )----------)-------. * * / \ | '---' | __|__ * * /___\ | | \ / * * | '-------------. | \ / * * A ----------------' | | o * * .-------------------. o-----)-------' | * * | |___.---. | |___.---. * * B ---*---.__.---. ___| )--*--.__..---. ____) )----- Y * * __| o----*--' '---' ______)) )---' '---' * * C -------' '---' | | ''---' * * | o * * | / \ * * | /___\ * * | | * * '--------------' * ************************************************************************************************* Analog Circuits -------------------------------------------------------------------------------- ************************************************* * * * k x₂ * * .---.╱╲╱╲╱╲╱'---. .-----> * * | | .+. * * ----+ *--+ m₂+---> * * | ---. | '-' x₁ * * '--------┫+-----' * * ---' * * d * * * ************************************************* Gantt Chart -------------------------------------------------------------------------------- ************************************************************************************************* * ║ Preproduction┆ Alpha┆ RC1┆ * ═══════════╬══════════════╪════════════╪════════════════╪══ * Story ║ ▆▆▆▆▆▆▆▆ ┆ ▆┆▆▆▆ ┆ * Concept Art║ └▆▆▆▆▆▆┆▆▆▆┐ ┆ ┆ * Modeling ║ ┆ └▆▆▆▆▆▆▆▆┆▆▆▆▆▆▆▆ ┆ * Rigging ║ ┆ └▆▆▆┆▆▆▆▆▆▆▆▆▆▆▆▆ ┆ * Mechanics ║ ▆▆▆▆▆▆┆▆▆┐ ┆ ░░░░▆▆▆▆ ┆ * Engine Code║ ▆▆▆▆▆▆▆┐ │ ┆ └────────▆┆▆▆▆▆▆▆▆▆▆▆▆▆▆ ┆ * Game Code ║ └─┴▆┆▆▆▆▆▆▆▆▆▆▆▆▆┆▆▆▆▆ ░░░░ ▆ ┆ * ║ ┆ ┆ Freeze ┆ ************************************************************************************************* Big Shapes -------------------------------------------------------------------------------- ************************************************************************************************* * * * .---------. . .-------. .-------. .---------. .-----. .----. * * \ / / \ \ \ | | | | / \ / \ * * \ / / \ \ \ | | | | / \ | | * * \ / / \ \ \ | | | | \ / | | * * \ / / \ \ \ | | | | \ / \ / * * ' '---------' '-------' '-------' '---------' '-----' '----' * * * ************************************************************************************************* Small Shapes -------------------------------------------------------------------------------- ************************************************************************************************* * .---. __ .. * * .--. . .-----. \ / .---. .---. ___ ___ | | | ) * * / \ / \ \ / .-. . ' . | | .---. .---. | | / \ | | '--' '' * * \ / / \ \ / | | / \ / \ '---' / / \ \ | | \___/ |___| .. __ * * '--' '-----' ' '-' '---' /___\ '---' '---' '---' ( | |__| * * '' * ************************************************************************************************* Overlaps and Intersections -------------------------------------------------------------------------------- ************************************************************************************************* * * * .-. .-. .-. .-. .-. .-. * * | | | | | | | | | | | | * * .---------. .--+---+--. .--+---+--. .--| |--. .--+ +--. .------|--. * * | | | | | | | | | | | | | | | | | | * * '---------' '--+---+--' '--+---+--' '--| |--' '--+ +--' '--|------' * * | | | | | | | | | | | | * * '-' '-' '-' '-' '-' '-' * ************************************************************************************************* Big Grids -------------------------------------------------------------------------------- ************************************************************************************************* * .----. .----. * * / \ / \ .-----+-----+-----. * * + +----+ +----. | | | | .-----+-----+-----+-----+ * * \ / \ / \ | | | | / / / / / * * +----+ B +----+ + +-----+-----+-----+ +-----+-----+-----+-----+ * * / \ / \ / | | | | / / / / / * * + A +----+ +----+ | | B | | +-----+-----+-----+-----+ * * \ / \ / \ +-----+-----+-----+ / / A / B / / * * '----+ +----+ + | | | | +-----+-----+-----+-----+ * * \ / \ / | A | | | / / / / / * * '----' '----' '-----+-----+-----' '-----+-----+-----+-----+ * * * ************************************************************************************************* Small Grids -------------------------------------------------------------------------------- ************************************************************************************************* * ___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---. * * ___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ | * * / \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ +---+ * * \___/ b \___/ \ | | | b | | | \ / \a/ \b/ \ / \ | +---+ | * * / a \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ b +---+ * * \___/ \___/ \ | | a | | | | / \ / \ / \ / \ / | a +---+ | * * \___/ \___/ '---+---+---+---+---' '---+---+---+---' '---' '---' * * * ************************************************************************************************* Tiny Grids -------------------------------------------------------------------------------- ************************************************************************************************* * ┌─┬─┬─┬─┬─┐ ▉▉ ▉▉ ▉▉ ⬢ ⬡ ⬡ ┌┬┬┬┬┬┬┬┬┐ ⁚⁚⁚⁚⁚⁚⁚⁚⁚⁚ ___________ +-+-+-+-+ * * ├─┼─┼─┼─┼─┤ ▉▉ ▉▉ ⬢ ⬢ ⬡ ⬡ ├┼┼┼┼┼┼┼┼┤ ⁚⁚⁚⁚⁚⁚⁚⁚⁚⁚ |__|__|__|__| +-+-+-+-+ * * ├─┼─┼─┼─┼─┤ ▉▉ ▉▉ ▉▉ ⬢ ⬢ ⬢ ⬡ ⬡ ├┼┼┼┼┼┼┼┼┤ ⁚⁚⁚⁚⁚⁚⁚⁚⁚⁚ |__|__|__|__| +-+-+-+-+ * * ├─┼─┼─┼─┼─┤ ▉▉ ▉▉ ⬡ ⬡ ⬡ ⬡ ├┼┼┼┼┼┼┼┼┤ ⁚⁚⁚⁚⁚⁚⁚⁚⁚⁚ |__|__|__|__| +-+-+-+-+ * * └─┴─┴─┴─┴─┘ ▉▉ ▉▉ ▉▉ ⬡ ⬡ ⬡ └┴┴┴┴┴┴┴┴┘ ⁚⁚⁚⁚⁚⁚⁚⁚⁚⁚ |__|__|__|__| +-+-+-+-+ * ************************************************************************************************* Dot Grids -------------------------------------------------------------------------------- ************************************************************************************************* * * * o o o o o * * * * * * * o o * o o o * * * o o o · * · · · · · · * * o o o o o * * * * * o o o o * o o o o * * * * * o * * · * * · · · · · · * * o o o o o * * * * * o * o o o o o o o o * * * * * o o o o o · o · · o · · * * · * * o o o o o * * * * * o * o o o o o o o * * * * o * o o · · · · o · · * · * * o o o o o * * * * * * * * * o o o o * * * o * o · · · · · · · * * * * ************************************************************************************************* Unicode in Diagram -------------------------------------------------------------------------------- ************************************************************************************************ * ↖ ↗ ✶ ✹ ✩ ⓵ ⎲ ░░▒▒▓▓██ ▚▚ ▢ ▢ ⬚ ⬚ ⊕ * ▲ ◀━━━━━━━▶ ↙ ↘ ➊ ❶ ➀ ① ➕ ➖ ➗ ❌ ⎳ ╲ ╱ ░░▒▒▓▓██ ▚▚ ▢ ▢ ⬚ ⬚ ⊜ * ┃ ╭╌╌╌╌╌╌╌╮ ╔═══════╗ ┏━━━━━━━┓ ┏╍╍╍╍╍╍╍┓ ╲ ╱ ░░▒▒▓▓██ ▚▚ ⬣ ⬣ ⎔ ⎔ ⊗ * ┃ ╎ ╎ ║ ║ ┃ ┃ ╏ ╏ ⎛ ⎧ ⎡ ╳ ░░▒▒▓▓██ ▚▚ ⬣ ⬣ ⎔ ⎔ ⊘ * ┃ ╎ ╎ ║ ║ ┃ ┃ ╏ ╏⋮ ⎜ ⎨ ⎢ ╱ ╲ ░░▒▒▓▓██ ▚▚ ◯ ◯ ⏣ ⏣ ⊙ * ▼ ╰╌╌╌╌╌╌╌╯ ╚═══════╝ ┗━━━━━━━┛ ⋱ ┗╍╍╍╍╍╍╍┛⋮ ⎝ ⎩ ⎣╱ ╲ ░░▒▒▓▓██ ▚▚ ◯ ◯ ⏣ ⏣ ⊛ * ⋱ ⋮ ◢██◣ * ∑xᵢ 𝚺xᵢ ∫t²dt ┳ ⋱ ⋮ ◥██◤ * | * ┣--+--┫ * | * ┻ ************************************************************************************************ Simple Plot Diagram ------------------------------------------------------------------------------- ************************************************* * ▲ * Uin ┊ .------------------------ * ┊ | * ┊ | * *---'┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄▶ * * Udc▲ * Udc_OK ┊ .--------------------- * ┊ / : * ┊ / : * *---'┄┄┄┄:┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄▶ * :<----->: * ▲ 500ms : * ┊ : *Cpu.Qon ┊┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄.----------- * ┊ | Inactive * ┊ Active | * *----------------'┄┄┄┄┄┄┄┄┄┄┄▶ * ************************************************* Graphics Diagram ------------------------------------------------------------------------------- ************************************************************************************************* * . * * 0 3 P * Eye / ^ / * * *-------* +y \ +) \ / Reflection * * 1 /| 2 /| ^ \ \ \ v * * *-------* | | v0 \ v3 --------*-------- * * | |4 | |7 | ◄╮ *----\-----* * * | *-----|-* ⤹ +-----> +x / v X \ .-.<-------- o * * |/ |/ / ⤴ / o \ | / | Refraction / \ * * *-------* v / \ +-' / \ * * 5 6 +z v1 *------------------* v2 | o-----o * * v * ************************************************************************************************* Annotated Table Diagram -------------------------------------------------------------------------------- ********************************************** * ┏━━━━┳━━━━┳ ┳━━━━┓ * ┃ A₁ ┃ A₂ ┃ ⋯ ┃ Aⱼ ┃ <--- Basis * ┡━━━━╇━━━━╇ ╇━━━━┩ * │ 16 │ 4 │ ⋯ │ 9 │ * ⎧ ├────┼────┼ ┼────┤ * │ │ 1 │ -2 │ ⋯ │ 10 │ * Xᵢ ⎨ ├────┼────┼ ┼────┤ * │ │ 8 │ 52 │ ⋯ │ 0 │ * ⎩ ├────┼────┼ ┼────┤ * │ 14 │ 0 │ ⋯ │ -1 │ * └────┴────┴ ┴────┘ ********************************************** Icon Diagram -------------------------------------------------------------------------------- ************************************************************************************************* * .-. .--------. * * .-+ | | | * * .--+ '--. |'--------'| * * | Server Cloud |<------------------>| Database | * * '-------------' | | * * ^ ^ '--------' * * Internet | | ^ * * .------------------------' '-------------. | * * | | v * * v v .------. .------. * * .--------. WiFi .--------. Bluetooth .-----. / # # /| / # # /| * * | |<------------->| |<---------->| | +------+/| LAN +------+/| * * |Windows | | OS X | | iOS | | +/|<--->| +/| * * +--------+ +--------+ | | |Ubuntu+/| |Ubuntu+/| * * /// ____ \\\ /// ____ \\\ | o | | +/ | +/ * * '------------' '------------' '-----' '------' '------' * * Laptop 1 Laptop 2 Tablet 1 Dedicated Server Rack * ************************************************************************************************* Styling Diagrams ------------------------------------------------------------------------------------ You can use CSS to style all diagrams or individual diagrams. For example, the following has light lines on a dark background:
**************************************************** * .---. . .----o----. * * | | | | | | * * | | --. |.-- | | *----*<---+ * * | | .-.| | +--+ | |____| * * | | | | | | | | | | * * '---' '-'' ' ' ' o----o--->' * ****************************************************
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: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ none ----- - - - _____ _ _ _ ***** * * * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Example: ----- - - - _____ _ _ _ ***** * * * Embedded Math ======================== Markdeep automatically includes [MathJax](http://mathjax.org) 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, \wo) = \Le(X, \wo) + \int_\Omega \Li(X, \wi) ~ f_X(\wi, \wo) ~ | \n \cdot \wi | ~ d\wi $$ You can also use LaTeX equation syntax directly to obtain numbered equations: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \begin{equation} e^{i \pi} + 1 = 0 \end{equation} \begin{equation} \label{linear} \mathbf{A}^{-1}\vec{b} = \vec{x} \end{equation} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ \begin{equation} e^{i \pi} + 1 = 0 \end{equation} \begin{equation} \label{linear} \mathbf{A}^{-1}\vec{b} = \vec{x} \end{equation} You can then reference those equations by name in the same way as figures, tables, and listings: `See eqn. [linear]` ==> See eqn. [linear]. 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: - $x^2$ - $ x^2 $ - ($x^2$) - ($ x^2 $) - Variable $x^2$, - Variable $ x^2 $ - Two $x$ vars $y$ on the same line - Different spacing styles: $\theta_{x}$ vs. $ \theta_{y} $ 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` | $\mathbf{M}^\T$ `45\degrees` | $45\degrees$ `x \in \Real` | $x \in \Real$ `x \in \Integer` | $x \in \Integer$ `x \in \Boolean` | $x \in \Boolean$ `x \in \Complex` | $x \in \Complex$ `\n` | $\n$ `\w` | $\w$ `\wo` | $\wo$ `\wi` | $\wi$ `\wh` | $\wh$ `\Li` | $\Li$ `\Lo` | $\Lo$ `\Lr` | $\Lr$ `\Le` | $\Le$ `\thetai` | $\thetai$ `\thetao` | $\thetao$ `\int x^2 ~\d{x}` | $\int x^2~\d{x}$ `10\un{m/s^2}` | $10\un{m/s^2}$ # 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](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Columns/Using_multi-column_layouts) 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 that you don't like about the built-in styling. For example, if you don't want section numbering, just use: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 ------------------------------------------------------------------------ See the [Markdeep website](https://casual-effects.com/markdeep/#templates) for a full set of templates and 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. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ html ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Localization =================================================== There are two ways to localize the keywords such as Table, Diagram, Monday, etc., from English to another natural language. The first is to put a meta tag with a [`lang`](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry) attribute in the document, such as <`meta lang="es" charset="utf-8"`>. The second method is to manually set the `markdeepOptions.lang` option in a `script` tag before you include Markdeep in your document, such as: `var markdeepOptions = {lang: "es"}`. When you've selected a language, keywords that you type such as "figure", "listing", etc., the names of days and months, and any text inserted by Markdeep such as "contents" will all be in that language. The currently supported language options are:
If your favorite language isn't supported by Markdeep, just [email me](mailto:morgan@casual-effects.com) a JavaScript snippet with the appropriate translations and I'll add it. See the source code for examples. 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). - Asian characters 林花謝了春紅 太匆匆, 無奈朝來寒雨 晚來風 胭脂淚 留人醉 幾時重, 自是人生長恨 水長東 - Asian punctuation:　、。！，： - Matching pairs «»‹›“”‘’〖〗【】「」『』〈〉《》〔〕 - Greek ΑΒΓΔ ΕΖΗΘ ΙΚΛΜ ΝΞΟΠ ΡΣΤΥ ΦΧΨΩ αβγδ εζηθ ικλμ νξοπ ρςτυ φχψω - Currency ¤ $ ¢ € ₠ £ ¥ - Common symbols © ® ™ ² ³ § ¶ † ‡ ※ - Bullets •◦ ‣ ✓ ●■◆ ○□◇ ★☆ ♠♣♥♦ ♤♧♡♢ - Phonetic ᴁ ᴂ ᴈ - Music ♩♪♫♬♭♮♯ - Punctuation “” ‘’ ¿¡ ¶§ª - ‐ ‑ ‒ – — ― … - Accents àáâãäåæç èéêë ìíîï ðñòóôõö øùúûüýþÿ ÀÁÂÃÄÅ Ç ÈÉÊË ÌÍÎÏ ÐÑ ÒÓÔÕÖ ØÙÚÛÜÝÞß - Math ° ⌈⌉ ⌊⌋ ∏ ∑ ∫ ×÷ ⊕ ⊖ ⊗ ⊘ ⊙ ⊚ ⊛ ∙ ∘ ′ ″ ‴ ∼ ∂ √ ≔ × ⁱ ⁰ ¹ ² ³ ₀ ₁ ₂ π ∞ ± ∎ - Logic & Set Theory ∀¬∧∨∃⊦∵∴∅∈∉⊂⊃⊆⊇⊄⋂⋃ - Relations ≠≤≥≮≯≫≪≈≡ - Sets ℕℤℚℝℂ - Arrows ←→↑↓ ↔ ↖↗↙↘ ⇐⇒⇑⇓ ⇔⇗ ⇦⇨⇧⇩ ↞↠↟↡ ↺↻ ☞☜☝☟ - Computing ⌘ ⌥ ‸ ⇧ ⌤ ↑ ↓ → ← ⇞ ⇟ ↖ ↘ ⌫ ⌦ ⎋⏏ ↶↷ ◀▶▲▼ ◁▷△▽ ⇄ ⇤⇥ ↹ ↵↩⏎ ⌧ ⌨ ␣ ⌶ ⎗⎘⎙⎚ ⌚⌛ ✂✄ ✉✍ - Digits ➀➁➂➃➄➅➆➇➈➉ - Religious and cultural symbols ✝✚✡☥⎈☭☪☮☺☹☯☰☱☲☳☴☵☶☷ - Dingbats ❦☠☢☣☤♲♳⌬♨♿ ☉☼☾☽ ♀♂ ♔♕♖ ♗♘♙ ♚♛ ♜♝♞♟ 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](http://g.gravizo.com/) within a Markdeep document using either direct Markdeep image syntax or an embedded HTML `img` tag: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![](http://g.gravizo.com/svg?digraph G { A -> B -> C; A -> C; }) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ![](http://g.gravizo.com/svg?digraph G { A -> B -> C; A -> C; }) Markdeep also allows captions on Gravizo graphs and newlines within the URL itself: ![Figure [graph]: A more complex graph example](http://g.gravizo.com/svg? digraph G { main -> parse -> execute; main -> init; main -> cleanup; execute -> make_string; execute -> printf init -> make_string; main -> printf; execute -> compare; }) Embedding Documents =================================================== Markdeep in iframe --------------------------------------------------- ### `src` Markdeep content generally works well in a HTML iframe. If embedded via the `src` attribute with a URL, it functions as if the iframe were a small web browser of its own. In that case you may want to use the optional link attributes to force links to open in the top context or a new window: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ html [CBC](https://cbc.ca target="_blank") ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ### `srcdoc` When embedded in a `srcdoc` inline, Markdeep still works well but links must be handled specially. It automatically adds the `target="_blank"` to externally page links to prevent them from breaking. Markdeep in Markdeep --------------------------------------------------- Markdeep can embed/insert/include other Markdeep documents inline, so that flow and links between them work seamlessly and they share a single table of contents. This is convenient for multi-chapter books, 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 is an example of embedding `example.md.html` into `features.md.html`: (insert example.md.html here) Other File Types --------------------------------------------------- It is not possible (for browser security reasons) to embed non-Markdeep documents inline, however you can embed _within a box_ any plain text document. For example:
`(embed example.py here)`
Yields the result: (embed example.py here) To change the height of the embedded box, add the height option:
`(embed example.py height=100px here)`
Yields the result: (embed example.py height=100px here) Differences from Other Markdown =================================================== Features --------------------------------------------------- There are many, inconsistent markdown variants. Markdeep intentionally differs from a few of them in specific ways: - Code blocks require fences; no indent-only code blocks. I think that allowing indentation to indicate code blocks was a poor choice in the original markdown specification because code vs. blockquote is ambiguous in plain text and it makes list detection harder. - Two trailing whitespace characters do not force a hard newline. Use `
` or regular paragraph breaks if you need a hard newline. The original markdown specification on this point violates its golden rule that the input look as much as possible like the output, and that rule also ends up requiring special code editors/syntax highlighting to see invisible characters, which is bad design. - No bold/italic/strikethrough inside of words without spaces because they could form an equation or technical term. Just use HTML tags. - Setext headers require at least three minus or equals characters to distinguish from multiline equations - Whitespace required between `#` and the section name for ATX headers (disambiguates "#1" from a header; required by CommonMark) - Markdeep's table reference syntax differs from MultiMarkdown's in order to provide a consistent formatting syntax across sections, figures, and tables...and one for which the source text is more readable. - Blockquotes must be two lines long (use explicit HTML if you really need a single-line blockquote) or contain quotation marks to disambiguate them from lines where a greater-than sign just wrapped around. - Escaped characters such as `\*` and `\_` are not needed, since Markdeep heuristics for determining when those characters are part of text and not formatting. Temporary Limitations --------------------------------------------------- Future releases likely will address these known bugs, limitations, and "missing features": - Tables and diagrams in lists create a new list - Listings have a maximum caption length of three lines Permanent Limitations --------------------------------------------------- Due to the special protection from formatting that Markdeep affords `
` and `` 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.

Images cannot appear within hyperlinks, because Markdeep adds a number
of features on top of images (e.g., captions, tables, video, audio,
floating) that would interfere. To put an image in a link, use an HTML
image. For example:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ none
[Link  with image](https://myurl)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~