Moon's Mark Down

by David A. Moon
December 2016



Directives

MMD supports the following directives:

Table of Contents Directives

.chapter, .section, and .subsection produce a table of contents in the index.html file. Each chapter goes in its own .html file.

HTML Directives

.html inserts raw HTML directly into the formatted output. No character translation occurs.

.prehtml and .posthtml are similar but insert before or after, respectively, the body of every page.

Cross-Reference Directives

.see chapter#anchor parses its directed line into a chapter name and an anchor name. If the chapter name is missing, it is the current chapter. If the # and its following anchor name is missing, it is the beginning of the chapter. .see inserts a cross-reference to the specified anchor in the specified chapter, formatted as "see anchor", or as "see chapter" when anchor is missing. The word "see" is capitalized if and only if the directive itself is capitalized.

.anchor treats its directed line as an anchor name and inserts that anchor.

Implicit Anchor

.chapter, .section, and .subsection implicitly insert an anchor whose name is the title downcased, with special characters removed, and with spaces changed to underscores.

Comment Directive

.comment ignores its directed lines. This can be used to hide (comment-out) portions of the input.

Code Directive

.code directs a block-quote of programming language source code. Note that flag characters are not recognized, as in all directed lines.

For example,

.code
def fib(x)
  if x < 2 then x
  else fib(x - 1) + fib(x - 2)
.end code
formats as:
def fib(x)
  if x < 2 then x
  else fib(x - 1) + fib(x - 2)

.codestyle html-style specifies the style for .code following.

For example,

.codestyle display: table; border: 1px solid red; background-color:yellow
causes the code to be enclosed in a red box with a yellow background, both sized to the same width as the code.

Sequence Diagrams

A sequence diagram graphically portrays a sequence of "events" among a set of "participants." Events are represented by arrows from one participant to another.

For example, this markdown:

.sequence
set arrow color green
set note color lightsalmon
set title size 25
set text size 15
set row height 45
participant A color orange  "Alice"
participant B color skyblue "Bob"
participant C color green   "Carol"
A->B "message 1"
A->C
:B->A "ack 1"
:A->B "message 2"
A->C@late "message 2"
note right "arrives late"
:B->A "ack 2"
late:C->A "ack 2"
.end sequence

produces this output:

Alice Alice Bob Bob Carol Carol message 1 ack 1 message 2 message 2 ack 2 ack 2 arrives late Sorry, your browser does not support inline SVG so it cannot display this sequence diagram.

Sequence Diagram Syntax

The description of a sequence diagram consists of three sections: settings, participants, and events. Each section consists of zero or more lines containing words, numbers, and strings enclosed in double quotes.

Colors can be any HTML color name, "rgb(red, green, blue)", "#RRGGBB", "hsl(hue, saturation, luminance)", etc.

Participant

A participant line is participant name [ color color ] [ description ] where square brackets indicate optional items.

Each participant owns a column in the sequence diagram. The description appears as boxed text at the head and foot of the column. If unspecified, description defaults to name. The color specifies the background color behind the description. If unspecified, color defaults to the participant color parameter.

name can be used in arrow lines to refer to this participant.

Event

Events define the main content of the sequence diagram. Events are organized into rows. Multiple events can appear in the same row, which typically means they happen at the same time. Rows proceeding down the page typically represent events happening at successive times.

An event is an arrow, a label, or a note. For convenience a label and an arrow can be specified in the same line of text, the label first.

An arrow line is from_name [ @ from_label ] -> to_name [ @ to_label ] [ string ].

This specifies an arrow from the from_name participant to the to_name participant. The row of each end point can be specified with an @ otherwise the end point is in the current row. If string is specified it is text that appears just above the arrow.

A label line is [ name ] :.

This specifies that the following events will be in the next row. If a name is given, this row can be referenced with @ to specify an arrow to or from this row.

A note line is note ( left | right ) [ color color ] string where | indicates alternatives and ( ) delimit the scope of |.

This specifies a textual note to appear to the left or right of the immediately preceding arrow. The string supplies the text of the note and color (which defaults to the note color parameter) supplies the background color behind that text.

The text of a note must fit on a single line.

Setting

A setting line is set parameter name value. This can be used to customize the layout and appearance of the diagram.

The parameters that can be set are:

Parameter Name Default Purpose
row height 60 HTML units per row
column width 150 HTML units per column
title size 20 HTML text size of participant descriptions
text size 15 HTML text size of notes and of arrow labels
arrow color red color of arrows
note color yellow background color behind note text
participant color pale yellow background color behind participant description


Previous page   Table of Contents   Next page



Creative Commons License
MMD by David A. Moon is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Please inform me if you find this useful, or use any of the ideas embedded in it.
Comments and criticisms to dave underscore moon atsign alum dot mit dot edu.