<c:red>set this string to red

<c:#white.blue>White foreground, blue background

<c:#.green300>green300 background

# make sure we have no tabs
$content =~ s/\t/    /gsm ;
$content = "ditaa\n$content" ;

# and process with the normal uml command
$params->{png} = 1 ;
return run_block( 'uml', $content, $params, $cachedir ) ;

}

</table>

#### External content

Its is possible to bring in content from another file by using the *file* attribute.

    ~~~~{.table file="/tmp/data.csv"}
    ~~~~

This is also valid when using short cuts

    \{\{.table file="/tmp/data.csv"}}

### Code-block short cuts

Sometimes using a fenced code-block is overkill, especially if the command to be executed does not have any content. So there is a shortcut to this. Additionally this will allow you to use multiple commands on a single line, this may be important in some instances.

Finally note that the shortcut must completely reside on a single line, it cannot span onto a separate next line, the parser will ignore it!

We wrap the command and its arguments with double braces.

<table class='box' width='99%'>
<tr><th width='100%'>Example</th></tr>
<tr>
<td>
    \{\{.tag argument1='fred' arg2=3}}
</td></tr></table>

Its is possible to add content that would normally be within the fenced code-block, if there is not too much information, by adding it to a *content* attribute.

We can see this in action below and in the barcode examples later on.

<table class='box' width='99%'>
<tr><th width='100%'>Example</th></tr>
<tr>
<td>
    \{\{.tag argument1='fred' arg2=3 content='some text'}}
</td></tr></table>

## Buffers

Sometimes you may either want to repeatedly use the same information or may want to use the output from one of the fenced code-blocks .

To store data we use the **to_buffer** argument to any code-block.

~~~~{.buffer to_buffer='spark_data'}
1,4,5,20,4,5,3,1

~~~~{.buffer to_buffer='spark_data'}
1,4,5,20,4,5,3,1
~~~~

If the code-block would normally produce some output that we do not want displayed at the current location then we would need to use the no_output argument.

    from_buffer='spark_data' to_buffer='greenspark' no_output=1}

~~~~{.sparkline title='green sparkline' scheme='green'
    from_buffer='spark_data' to_buffer='greenspark' no_output=1}
~~~~

We can also have the content of a code-block replaced with content from a buffer by using the from_buffer argument. This is also displayed in the example above.

To use the contents (or output of a buffered code-block) we wrap the name of the buffer once again with percent '%' symbols, once again we force upper case.

%SPARK_DATA% has content %SPARK_DATA%
%GREENSPARK% has a generated image %GREENSPARK%

Buffering also allows us to add content into markdown constructs like bullets.

* %SPARK_DATA%
* %GREENSPARK%

By using setting an ifnot attribute to a true value, it is possible to only set the contents of the buffer if the buffer is currently empty. This is useful in cases where a parent document wants to set a value and a child document, which may be used in other documents wants to have a default for instances when the parent document is not providing a value.

~~~~{.buffer ifnot=1 to=buffer_name}
default_value
~~~~

The text plugin has lots of simple handlers, they all output text/HTML.

Software engineers often use [JSON] to transfer data between systems, this often is not nice to create for documentation. [YAML] which is a superset of [JSON] is much cleaner so we have a

~~~~{.yamlasjson }
list:
  - array: [1,2,3,7]
    channel: BBC3
    date: 2013-10-20
    time: 20:30
  - array: [1,2,3,9]
    channel: BBC4
    date: 2013-11-20
    time: 21:00
~~~~

Software engineers often use [XML] to transfer data between systems, this often is not nice to create for documentation. We cam create basic XML, we do not allow element attributes. If you want real XML layout use .xml in a fenced code block.

~~~~{.yamlasxml }
list:
  - array: [1,2,3,7]
    channel: BBC3
    date: 2013-10-20
    time: 20:30
  - array: [1,2,3,9]
    channel: BBC4
    date: 2013-11-20
    time: 21:00
~~~~

Create a simple table using CSV style data

• class
  • HTML/CSS class name
• id
  • HTML/CSS class
• width
  • width of the table
• style
  • style the table if not doing anything else
• legends
  • if true first line csv as headings for table, these correspond to the data sets
• separator
  • what should be used to separate cells, defaults to ','
• align
  • align the table, left, middle/center (default), right
• sort
  • column number to sort on, append 'r' to reverse the sort

• title
  • add a caption to the table

Date,Item,Cost
2012-06-25, Tree, 23.99
2015-04-20, Shed, 400.00
2010-03-02, Lawn mower, 69.95
2014-12-12, Gnome, 7.95

~~~~{.table separator=',' width='100%' legends=1 title='a caption'}
%TABLE_DATA%
~~~~

The table can be sorted too, reverse date (newest first)

~~~~{.table separator=',' width='100%' legends=1 sort='0r'}
%TABLE_DATA%
~~~~

This is very similar to Table but styled to look like a spreadsheet

• class
  • HTML/CSS class name
• id
  • HTML/CSS class
• width
  • width of the table
• style
  • style the table if not doing anything else
• legends
  • if true first line csv as headings for table, these correspond to the data sets
• separator
  • what should be used to separate cells, defaults to ','
• align
  • align the table, left, middle/center (default), right
• sort
  • column number to sort on, append 'r' to reverse the sort

• title
  • add a caption to the table
• worksheets (sheets)
  • adds 'tabs' to the spreadsheet, also adds a couple of blank rows to separate the spreadsheet from the rows
  • csv of sheets in a workbook.
  • to set one as active preceed name with '!'
  • i.e. 'Sheet 1, !Sheet 2, Sheet 3' will highlight 'Sheet 2' as the active sheet

The same cell align and color options from table are valid here too.

~~~~{.spreadsheet separator=',' width='100%' legends=1
  title='its a spreadsheet' worksheets='Sheet 1, !Sheet 2, Sheet 3'}
%TABLE_DATA%
~~~~

The spreadsheet can be sorted too, reverse date (newest first)

~~~~{.spreadsheet separator=',' width='100%' legends=1 sort='0r'
   worksheets='Sheet 1, !Sheet 2, Sheet 3'}
%TABLE_DATA%
~~~~

With one code-block we can create a list of links

The code-block contents comprises a number of lines with a reference and a URL. The reference comes first, then a '|' to separate it from the URL.

The reference may then be used elsewhere in your document if you enclose it with square ([]) brackets

There is only one argument

• class
  • CSS class to style the list

These links used in this example are the ones used in this document.

pandoc      | https://johnmacfarlane.net/pandoc
PrinceXML   | https://www.princexml.com
Markdown    | https://daringfireball.net/projects/markdown
msc         | https://www.mcternan.me.uk/mscgen/
ditaa       | https://ditaa.sourceforge.net
PlantUML    | https://plantuml.sourceforge.net
Salt        | https://plantuml.sourceforge.net/salt.html
graphviz    | https://graphviz.org
JSON        | https://en.wikipedia.org/wiki/Json
YAML        | https://en.wikipedia.org/wiki/Yaml
wkhtmltopdf | https://wkhtmltopdf.org/
My Github   | https://github.com/27escape/App-Basis-ConvertText2/tree/master/scripts
Brewer      | https://www.graphviz.org/content/color-names#brewer
README PDF  | https://github.com/27escape/App-Basis-ConvertText2/blob/master/docs/README.pdf
Font Awesome Cheatsheet | https://fontawesome.io/cheatsheet/
Google Material Font Cheatsheet | https://www.google.com/design/icons/
Google Colors | https://www.google.com/design/spec/style/color.html#color-color-palette
Emoji Cheatsheet | https://www.emoji-cheat-sheet.com

~~~~{.links class='weblinks' }
%WEBLINKS%
~~~~

Documents often need revision history. I use this code-block to create a nice version table of this history.

The content for this code-block comprises a number of sections, each section then makes a row in the generated table.

version YYYY-MM-DD
   indented change text
   more changes

The version may be any string, YYYY-MM-DD shows the date the change took place. Alternate date formats is DD-MM-YYYY and '/' may also be used as a field separator.

So give proper formatting to the content in the changes column you should indent text after the version/date line with 4 spaces, not a tab character.

• class
  • HTML/CSS class name
• id
  • HTML/CSS class
• width
  • width of the table
• style
  • style the table if not doing anything else

• title
  • create a title for the version table

0.1 2014-04-12
  * removed ConvertFile.pm
  * using Path::Tiny
0.006 2014-04-10
  * first release to github

~~~~{.version}
%VERSIONTABLE%
~~~~

There are 2 ways for force the start of a new page, using the .page fenced code block or by having 4 '-' signs next to each other, i.e. '----' on a line on their own

\{\{.page}}

as will this

----

Create a columner layout, like a newspaper. The full text in the content is split into columns, the height of the section is determined by the volume of the text.

The optional arguments are

• count
  • number of columns to split into, defaults to 2
• lines
  • number of lines the section should hold, defaults to 20
• ruler
  • show a line between the columns, defaults to no, options are 1, true or yes to show it
• width
  • how wide should the column area be, defaults to 100%

Flexitarian lo-fi occupy, Echo Park yr chia keffiyeh iPhone pug kale chips
fashion axe PBR&B 90's readymade beard.

McSweeney's Tumblr semiotics
beard, flexitarian artisan bitters twee small batch next level PBR mustache
post-ironic stumptown.

Umami Pinterest mixtape Truffaut, Blue Bottle ugh
artisan whatever blog street art Odd Future crucifix tomato shore invisible
spelling.

~~~~{.columns count=3 ruler=yes width='95%'}
%COLUMNS%
~~~~

This should generally be used as a short block as an easy way to increment appendix values in headings.

Appendicies will be created as 'Appendix A', 'Appendix B' etc.

* \{\{.appendix}}
* \{\{.appendix}}
* \{\{.appendix}}

This should generally be used as a short block as an easy way to increment counter values, e.g. in headings

The optional arguments are

• name
  • the name of the counter to increment, otherwise 'default' will be used
• start
  • start the counter from this number, defaults to '1'

* \{\{.counter name=fred}}
* \{\{.counter name=fred}}
* default \{\{.counter}}
* \{\{.counter name=martha start=100}}
* \{\{.counter name=martha}}

If its useful to comment your software, likely you will also find it useful to comment your documents. Having a comment construct allows sections to be removed/hidden too.

Normal flow of text

~~~~\{.comment}
This comment is not seen in the generated document
~~~~

text continues

This comment is not seen in the generated document

Import a file and indent it 4 spaces. This is useful if you want to pull code or config files etc into your document to explain them.

The optional arguments are

• class
  • add a div with this CSS class name
• style
  • add a div with this CSS style

Here is the example config file
\{\{.indent file=fred.conf style='background-color:grey50;'}}

text continues

Draw a percent bar

The required arguments are

• value
  • value of the percent, required, max 100, min 0

The optional arguments are

• color
  • color of the bar
• border
  • add a grey border to the box
• trigger
  • set the color based on the value, dark red, light red, orange, yellow, green
• width
  • width of the bounding box, ideally in px

* \{\{.percent value=90 border=1}} default color
* \{\{.percent value=20 trigger=1 }}
* \{\{.percent value=40 trigger=1 }}
* \{\{.percent value=55 trigger=1}}
* \{\{.percent value=75 trigger=1}}
* \{\{.percent value=100 trigger=1}}
* \{\{.percent value=50 width=75px color=pink}}

Draw a bulleted list as a directory tree. Bullets are expected to be indented by 4 spaces, we will only process bullets that are * + or -.

~~~~{.tree}
* one
    * 1.1
* two
    * two point 1
    * 2.2
* three
    * 3.1
    * 3.2
    * three point 3
        * four
            * five
        * six
    * 3 . seven
~~~~

Badges (or shields) are a way to display information, often used to show status of an operation on websites such as github.

Examples of shields can be seen at shields.io

The badges are placed inline, so you can insert text around the fenced codeblock.

Depending on your template the color of the text and the color for the status portion may clash, so take care!

The required argument are

• subject
  • text saying what the badge is
• status
  • text status to put at the end of the badge

The optional arguments are

• color
  • over ride the default color 'goldenrod'
  • can use #foreground.bgbackground format, ie #blue.yellow, or #ffffff.blue
• size
  • the size of the badge
• reverse
  • swap the colors around

~~~~{.badge subject='test run' status='completed' color='green'}
~~~~

\{\{.shield subject='test run' status='pending' size='150'}}

\{\{.shield subject='test run' status='pending' size='150' color='orange'
 reverse=1}}

\{\{.shield subject='test run' status='failed' size='150'
color='#white.red' }}

Buttons are like badges but with no status, just a simple styled item.

The buttons are placed inline, so you can insert text around the fenced codeblock.

The required argument are

• subject
  • text saying what the button is

The optional arguments are

• color
  • over ride the default background color 'purple300'
  • can use #foreground.bgbackground format, ie #blue.yellow, or #ffffff.blue
  • without a foreground color, this will default to white
• size
  • the width of the button
• icon
  • add an icon before the subject text
  • defaults to a font-awesome icon if there is no ':' prefix to fully specify the icon.
    • 'plus-circle' interpreted as ':fa:plus-circle'

~~~~{.button subject='test run' color='green'}
~~~~

\{\{.button subject='test run' size='150'}}

\{\{.button subject='test run' size='150'  color='#blue.yellow' }}

\{\{.button subject='test run' border='1'  }}

\{\{.button subject='test run' border='red'  }}

\{\{.button subject='test run' icon='plus-circle' color='green'}}

\{\{.button subject='Upload' icon='\:mi:file-upload' }}

Show that something is important by putting it in a box

The optional arguments are

• class
  • HTML/CSS class name
• id
  • HTML/CSS class
• width
  • width of the box (default 98%)
• title
  • optional title for the section
• style
  • style the box if not doing anything else

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Pellentesque sit amet accumsan est. Nulla facilisi.
Nulla lacus augue, gravida sit amet laoreet id,
commodo vitae velit. Fusce in nisi mi. Nulla congue
nulla ac bibendum semper. In rutrum sem eget purus
auctor porttitor. Mauris vel pellentesque lorem.
Vestibulum consectetur massa non fermentum dignissim.

~~~~{.box from_buffer=box
  title='Important Notice'
  width='80%'}
~~~~

Show that something is important by putting it in a box with an icon

This is the complete form of the Admonitions.

There are thirteen types

• note
• info
• tip
• important
• caution
• warning
• danger
• todo
• aside
• question
• fixme
• error
• sample - this is not provided as a shortcut as 'SAMPLE:'

The optional arguments are

• class
  • HTML/CSS class name
• id
  • HTML/CSS class
• width
  • width of the box (default 100%)
• title
  • optional title for the section
• style
  • style the box if not doing anything else
• icon
  • give the admonition an icon
  • '1' uses the default, otherwise use a Font Awesome or Google Material Font named icon, without :fa or :ma prefix, default will be for fontawesome.

{{.note explain=1 icon=1 content='sample text'}}

{{.info explain=1 icon=1 content='sample text'}}

{{.tip explain=1 icon=1 content='sample text'}}

{{.important explain=1 icon=1 content='sample text'}}

{{.warning explain=1 icon=1 content='sample text'}}

{{.caution explain=1 icon=1 content='sample text'}}

{{.danger explain=1 icon=1 content='sample text' style='background-color:green50;font-size:1.5em;'}}

{{.todo explain=1 icon=1 content='sample text, 70% width' width='70%'}}

{{.aside explain=1 icon=1 content='sample text' title='Try this'}}

{{.question explain=1 icon=1 content='There is a lot to read' title='Have you read the docs'}}

{{.note explain=1 icon=:mi:settings-bluetooth content='Google material icon' title='Bluetooth Settings' }}

{{.sample icon=1 explain=1 content='Some sample code or notes etc' title='Sample' }}

Build a glossary of terms or abbreviations as you progress with your document. Show them later on, there is no way (currently) to place the glossary ahead of any definitions.

Optionally if there is a link to a item e.g. \[Links](#links)
\{\{.gloss abbr='msc' define='Message Sequence Charts' link=1}}
then this can link to the relevant website, the following link
has not been added to
\{\{.gloss abbr='JSON' define='JavaScript Object Notation'}},
so no link to the website.

Now finally, show the results using \{\{.gloss show=1}} or to get a more complete section use \{\{.gloss show=complete}} which will create a level 2 appendix section

\{\{.gloss show=1}}

\{\{.gloss show=complete}}

If you find that you are using the same items in multiple documents, then you may wish to use a glossary file, this is a YAML file

\{\{.gloss yaml='somefile.yaml'}}

The YAML file has the format

glossary:
  abbr: definition
  BBC: British Broadcasting Company

then anytime that you use an abbreviation without a definition, then this will attempt to fetch the definition from the loaded YAML data
\{\{.gloss abbr='BBC'}}

Pandoc provides for blockquotes, these are often like

> a standard quote
> another line of the block
>
> And a final one

as

a standard quote another line of the block

And a final one

We want something that can be styled differently and can have a title

The optional arguments are

• class
  • HTML/CSS class name
• id
  • HTML/CSS class
• title
  • optional title for the section

Start by doing what's necessary;

then do what's possible;

and suddenly you are doing the
impossible.

~ Francis of Assisi

~~~~{.quote title='Title'
  width=100%}
%QUOTE%
~~~~

~~~~{.quote title='Title'
  width=350px}
%QUOTE%
~~~~

Sparklines are simple horizontal charts to give an indication of things, sometimes they are barcharts but we have nice smooth lines.

The only valid contents of the code-block is a single line of comma separated numbers.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• bgcolor
  • background color in hex (123456) or transparent
• line
  • color or the line, in hex (abcdef)
• color
  • area under the line, in hex (abcdef)
• scheme
  • color scheme
    • options: red blue green orange mono
• size
  • size of image, default 80x20, widthxheight

1,4,5,20,4,5,3,1

~~~~{.buffer
  to_buffer='spark_data'}
%SPARK_DATA%
~~~~

~~~~{.sparkline
  title='basic sparkline'}
%SPARK_DATA%
~~~~

~~~~{.sparkline
  title='blue sparkline'
  scheme='blue'
  from_buffer='spark_data'}
~~~~

Displaying charts is very important when creating reports, so we have a simple chart code-block.

A,B,C,D,E,F,G,H
1,2,3,5,11,22,33,55
1,2,3,5,11,22,33,55
1,2,3,5,11,22,33,55
1,2,3,5,11,22,33,55

We will buffer some data to start. The content comprises lines of comma separated data. The first line of the content is the legends; subsequent lines relate to each of these legends.

~~~~{.buffer to='chart_data'}
A,B,C,D,E,F,G,H
1,2,3,5,11,22,33,55
1,2,3,5,11,22,33,55
1,2,3,5,11,22,33,55
1,2,3,5,11,22,33,55
~~~~

~~~~{.chart format='pie'
  title='Pie'
  from_buffer='chart_data'
  size='300x300'}
~~~~

~~~~{.chart format='bars'
  title='Bars'
  from_buffer='chart_data'
  size='300x300'
  xaxis='things ways'
  yaxis='Vertical things'
  legends='A,B,C,D,E,F,G,H' }
~~~~

~~~~{.chart format='mixed'
  title='Mixed'
  from_buffer='chart_data'
  size='300x300'
  xaxis='things xways'
  axis='Vertical things'
  legends='A,B,C,D,E,F,G,H' }
  types='lines linepoints lines
    bars' }
~~~~

Message Sequence Charts

Software (or process) engineers often want to be able to show the sequence in which a number of events take place. We use the [msc] program for this. This program needs to be installed onto your system to allow this to work

The content for this code-block is EXACTLY the same that you would use as input to [msc]

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

# MSC for some fictional process
msc {
  a,b,c;

  a->b [ label = "ab()" ] ;
  b->c [ label = "bc(TRUE)"];
  c=>c [ label = "process(1)" ];
  c=>c [ label = "process(2)" ];
  ...;
  c=>c [ label = "process(n)" ];
  c=>c [ label = "process(END)" ];
  a<<=c [ label = "callback()"];
  ---  [ label = "If more to run" ];
  a->a [ label = "next()"];
  a->c [ label = "ac1()\nac2()"];
  b<-c [ label = "cb(TRUE)"];
  b->b [ label = "stalled(...)"];
  a<-b [ label = "ab() = FALSE"];
}

~~~~{.mscgen  title="mscgen1"
  width=350}
%MSCGEN%
~~~~

Software engineers love to draw diagrams, [PlantUML] is a java component to make this simple.

You will need to have a script on your system called 'uml' that calls java with the plantuml component. Mine is available from [My Github] repo.

The content for this code-block must be the same that you would use to with the [PlantUML] software

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

• align
  • align the generated image, left, center, right

' this is a comment on one line
/' this is a
multi-line
comment'/
Alice -> Bob: Auth Request
Bob --> Alice: Auth Response

Alice -> Bob: Auth Request 2
Alice <-- Bob: Auth Response 2

~~~~{.uml width=350}
%UML%
~~~~

[PlantUML] can also create simple application interfaces See [Salt]

@startsalt
{
  Just plain text
  [This is my button]
  ()  Unchecked radio
  (X) Checked radio
  []  Unchecked box
  [X] Checked box
  "Enter text here   "
  ^This is a droplist^

  {T
   + World
   ++ America
   +++ Canada
   +++ **USA**
   ++++ __New York__
   ++++ Boston
   +++ Mexico
   ++ Europe
   +++ Italy
   +++ Germany
   ++++ Berlin
   ++ Africa
  }
}
@endsalt

~~~~{.uml width=350}
%SALT%
~~~~

Plantuml can generate random sudoku patterns

~~~~{.uml width=350}
sudoku
~~~~

To always generate the same pattern, append a seed value after 'sudoku'

~~~~{.uml}
sudoku 45azkdf4sqq
~~~~

Draw a bulleted list as a tree using the plantuml salt GUI layout tool. Bullets are expected to be indented by 4 spaces, we will only process bullets that are * + or -.

* one
    * 1.1
* two
    * two point 1
    * 2.2
* three
    * 3.1
    * 3.2
    * three point 3
        * four
            * five
        * six
    * 3 . seven

~~~~{.umltree width=350}
%UMLTREE%
~~~~

Diagrams Through Ascii Art

This is a special system to turn ASCII art into pretty pictures, nice to render diagrams. You do need to make sure that you are using a proper monospaced font with your editor otherwise things will go awry with spaces.

Rather than use the [ditaa] application and to reduce the number of applications that need to be installed on the system, we use the ditaa component of plantuml. This does have some limitations, for example there is no way to switch spaces or shadows off. However this is a useful tradeoff

The content for this code-block must be the same that you would use to with the ditaa software.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

Full example
+--------+   +-------+   +-----+
|        +-->| ditaa +-->|     |
|  Text  |   +-------+   |image|
|Document|   |!magic!|   |     |
|     {d}|   |       |   |cBLU |
+---+----+   +-------+   +-----+
    :                       ^
    |       Lots of work    |
    \-----------------------+
           To do by hand

~~~~{.ditaa width=350}
%DITAA%
~~~~

[graphviz] allows you to draw connected graphs using text descriptions.

The content for this code-block must be the same that you would use to with the [graphviz] software

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

• command
  • command used to draw the graph, defaults to dot
    • options are dot, neato, twopi, fdp, sfdp, circo, osage

digraph G {

  subgraph cluster_0 {
    style=filled;
    color=lightgrey;
    node [style=filled,color=white];
    a0 -> a1 -> a2 -> a3;
    label = "process #1";
  }

  subgraph cluster_1 {
    node [style=filled];
    b0 -> b1 -> b2 -> b3;
    label = "process #2";
    color=blue
  }
  start -> a0;
  start -> b0;
  a1 -> b3;
  b2 -> a3;
  a3 -> a0;
  a3 -> end;
  b3 -> end;

  start [shape=Mdiamond];
  end [shape=Msquare];
}

~~~~{.graphviz  title="graphviz1"
  size=width=350}
  %GRAPHVIZ%
~~~~

There is no nice way to convert plain text to mindmaps, the only way normally would be to use graphviz or something similar.

However, converting a bulleted list into a simple mindmap would be ideal!

Each bulleted item would be a node in the mindmap.

Bullets can be '*', '+' or '-' and should be indented 4 spaces to indicate a child. Poor indenting can be managed to a degree.

There should be a single top level bullet, which is used as the root of the map, see the example below. Multiple top level bullets will result in a badly organised mindmap.

Markdown style bold and italics markers can be used, as can '\n' to start a new line in a node.

Comments can be added and will be ignored when rendering the mindmap, anything following ' :' will be considered as a comment.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

• command
  • command used to draw the graph, defaults to dot
    • options are dot neato twopi fdp sfdp circo osage

• scheme - color scheme to use - optional
  • default pastel28, schemes taken from [Brewer]
  • blue purple green grey mono orange red brown are shortcuts
• shapes - list of shapes to use - optional
  • default box ellipse hexagon octagon

Bullet text can override some shapes

• wrap in the following to get the required shape
  • [] shape=box
  • () shape=ellipse
  • <> shape=diamond
  • {} shape=octagon
• include a shape=
  • shape=box3d

Bullet text can include a color override

• #red or #123456 or #ff00ff

* base thought
  + (force ellipse)
      + in **bold**
  + another thing : ignore this
      + color red #red
  * put this\none\non a few\nlines

~~~~{.mindmap size=350x250}
%MINDMAP%
~~~~

~~~~{.mindmap shapes='box'
  scheme=green size=350x250}
%MINDMAP%
~~~~

Creating venn diagrams may sometimes be useful, though to be honest this implementation is not great, if I could find a better way to do this then I would!

~~~~{.venn  title="sample venn diagram"
    legends="team1 team2 team3" scheme="rgb" explain='1'}
abel edward momo albert jack julien chris
edward isabel antonio delta albert kevin jake
gerald jake kevin lucia john edward
~~~~

Sometimes having barcodes in your document may be useful, certainly qrcodes are popular.

The code-block only allows a single line of content. Some of the barcode types need content of a specific length, warnings will be generated if the length is incorrect.

The arguments allowed are

• title
  • used as the generated images 'alt' argument
• height
  • height of image
• notext
  • flag to show we do not want the content text printed underneath the barcode.
• version
  • version of qrcode, defaults to '2'
• pixels
  • number of pixels that is a 'bit' in a qrcode, defaults to '2'
• type
  • the type of the barcode
  • code39
  • coop2of5
  • ean8 - 8 characters allowed in content
  • ean13 - 13 characters allowed in content
  • iata20f5
  • industrial20f5
  • itf
  • matrix2of5
  • nw7
  • qrcode

~~~~{.barcode type='code39'}
123456789
~~~~

~~~~{.barcode type='ean8'}
12345678
~~~~

~~~~{.barcode type='IATA2of5'}
12345678
~~~~

As qrcodes are now quite so prevalent, they have their own code-block type.

We can do qr codes, just put in anything you like, this is a URL for bbc news

~~~~{.qrcode }
https://news.bbc.co.uk
~~~~

~~~~{.qrcode height='80'}
https://news.bbc.co.uk
~~~~

~~~~{.qrcode height=60 version=1}
smaller text..
~~~~

~~~~{.qrcode pixels=5}
smaller text..
~~~~

This is a complex graph/chart drawing package available from https://glx.sourceforge.net/

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, default 720x512, widthxheight, size is approximate
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

• title
  • used as the generated images 'alt' argument
• transparent
  • flag to use a transparent background

set font texcmr hei 0.5 just tc

begin letz
   data "saddle.z"
   z = 3/2*(cos(3/5*(y-1))+5/4)/(1+(((x-4)/3)^2))
   x from 0 to 20 step 0.5
   y from 0 to 20 step 0.5
end letz

amove pagewidth()/2 pageheight()-0.1
write "Saddle Plot (3D)"

begin object saddle
   begin surface
      size 10 9
      data "saddle.z"
      xtitle "X-axis" hei 0.35 dist 0.7
      ytitle "Y-axis" hei 0.35 dist 0.7
      ztitle "Z-axis" hei 0.35 dist 0.9
      top color blue
      zaxis ticklen 0.1 min 0 hei 0.25
      xaxis hei 0.25 dticks 4 nolast nofirst
      yaxis hei 0.25 dticks 4
   end surface
end object

amove pagewidth()/2 0.2
draw "saddle.bc"

~~~~{.gle}
%GLE%
~~~~

This is the granddaddy of charting/plotting programs, available from https://gnuplot.sourceforge.net/.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, default 720x512, widthxheight

set samples 21
set isosample 11
set xlabel "X axis" offset -3,-2
set ylabel "Y axis" offset 3,-2
set zlabel "Z axis" offset -5
set title "3D gnuplot demo"
set label 1 "surface boundary" at -10,-5,150 center
set arrow 1 from -10,-5,120 to -10,0,0 nohead
set arrow 2 from -10,-5,120 to 10,0,0 nohead
set arrow 3 from -10,-5,120 to 0,10,0 nohead
set arrow 4 from -10,-5,120 to 0,-10,0 nohead
set xrange [-10:10]
set yrange [-10:10]
splot x*y

~~~~{.gnuplot}
%GNUPLOT%
~~~~

This is a rather old school charting applitcation, though it can create some graphs and charts that the other plugins cannot, e.g. Timelines.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

Its best to let ploticus control the size of the generated images, you may need some trial and error with the ploticus 'pagesize:' directive.

~~~~{.ploticus}
//  specify data using proc getdata
#proc getdata
data: Brazil 22
  Columbia 17
  "Costa Rica" 22
  Guatemala 3
  Honduras 12
  Mexico 14
  Nicaragua 28
  Belize 9
  "United States" 21
  Canada 8

//  render the pie graph using proc pie
#proc pie
datafield: 2
labelfield: 1
labelmode: line+label
center: 4 3
radius: 1
colors: oceanblue
outlinedetails: color=white
labelfarout: 1.3
total: 256
~~~~

//  specify data using proc getdata

pagesize: 8 8

#proc getdata
data: Brazil 22
  Columbia 17
  "Costa Rica" 22
  Guatemala 3
  Honduras 12
  Mexico 14
  Nicaragua 28
  Belize 9
  "United States" 21
  Canada 8

//  render the pie graph using proc pie
#proc pie
datafield: 2
labelfield: 1
labelmode: line+label
center: 4 3
radius: 1
colors: oceanblue
outlinedetails: color=white
labelfarout: 1.3
total: 256

#proc getdata
data:
   NBC  8:00  9:00  "Wind\non Water"
   NBC  9:00  9:30  "Encore!\nEncore!"
   NBC  9:30  10:00 "Conrad\nBloom"
   NBC  10:00 11:00 "Trinity"
   ABC  8:00  8:30  "Secret\nLives"
   ABC  8:30  9:00  "Sports\nNight"
   ABC  9:00  11:00 "Movie of the Week"
   CBS  8:00  8:30  "Cosby"
   CBS  8:30  9:00  "Kids say..."
   CBS  9:00  10:00 "Charmed"
   CBS  10:00 11:00 "To have\nand to Hold"

#proc areadef
   title: Evening television schedule
   rectangle: 1 1 7 3
   xscaletype: time
   xrange: 08:00 11:00
   yscaletype: categories
   ycategories:
  NBC
  ABC
  CBS

#proc xaxis
   stubs: inc 1 hours

#proc yaxis
   stubs: categories

#proc bars
   color: powderblue2
   axis: x
   locfield: 1
   segmentfields: 2 3
   labelfield: 4
   longwayslabel: yes
   labeldetails: size=6

Display an image with a bounding box so it looks like a polaroid snap.

reate a polaroid style image with space underneath for writing on. Image may be automatically rotated depending upon the exif information

The required arguments are

• src
  • filename to convert to a polaroid

The optional arguments are

• title
  • title for the photo
• date
  • optional date for the photo

~~~~{.polaroid src='heartp.jpg'
  title='The heart of Paris'
  date='2015-02-06'}
~~~~

Blockdiag provides a number of ways to create nice diagrams. See https://blockdiag.com/ for more information, how to install and examples.

To keep things simple, we add the correct wrapper around the fenced codeblock, so that there is no need to add blockdiag { etc to the start and end of the blocks.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

• transparent
  • should the background be transparent, default true

Similar to graphviz, layout is more grid based.

note [shape = note];
mail [shape = mail];
cloud [shape = cloud];
actor [shape = actor];
note -> mail ;
mail -> cloud ;
mail -> thing ;
note -> actor;

~~~~{.blockdiag  width=350}
%BLOCKDIAG%
~~~~

One for the system administrators, draw your network nicely with the various networks and systems connected to them.

 network dmz {
 address = "210.x.x.x/24"

 web01 [address = "210.x.x.1"];
 web02 [address = "210.x.x.2"];
}
network internal {
 address = "172.x.x.x/24";

 web01 [address = "172.x.x.1"];
 web02 [address = "172.x.x.2"];
 db01;
 db02;
}

~~~~{.nwdiag  width=350}
%NWDIAG%
~~~~

Useful to describe packets of data, e.g. binary data passed between networks or stored to files.

colwidth = 32
node_height = 72

0-15: Source Port
16-31: Destination Port
32-63: Sequence Number
64-95: Acknowledgment Number
96-99: Data Offset
100-105: Reserved
106: URG [rotate = 270]
107: ACK [rotate = 270]
108: PSH [rotate = 270]
109: RST [rotate = 270]
110: SYN [rotate = 270]
111: FIN [rotate = 270]
112-127: Window
128-143: Checksum
144-159: Urgent Pointer
160-191: (Options and Padding)
192-223: data [colheight = 3]

~~~~{.packetdiag  width=350}
%PACKETDIAG%
~~~~

Useful for system administrators to keep track of their server rooms.

// define height of rack
10U;

// define rack items
1: UPS [2U];
3: DB Server
4: Web Server
5: Web Server
6: Web Server
7: Load Balancer
8: L3 Switch

~~~~{.rackdiag width=350}
%RACKDIAG%
~~~~

The classic swim lanes.

write -> convert -> image

lane user {
   label = "User"
   write [label = "request"];
   image [label = "done"];
}
lane server {
   label = "Server"
   convert [label = "process"];
}

~~~~{.actdiag}
%ACTDIAG%
~~~~

Very similar to the output of mscgen and uml tags.

browser  -> webserver
 [label = "GET /index.html"];

browser <-- webserver;

browser  -> webserver
 [label = "POST /blog/comment"];

webserver  -> database
 [label = "INSERT comment"];

webserver <-- database;
browser <-- webserver;

~~~~{.seqdiag}
%SEQDIAG%
~~~~

Dataflow diagrams allow multiple outputs from a single workflow description.

See https://github.com/sonyxperiadev/dataflow/blob/master/USAGE.md for more information, how to install and examples.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

• format
  • either dfd (default) or seq
• align
  • align the generated image, left, center, right

The example images are a bit compressed to fit in the table, normally they look a lot better than this!

diagram 'Webapp' {
  boundary 'Browser' {
    function client 'Client'
  }
  boundary 'Amazon AWS' {
    function server 'Web Server'
    database logs 'Logs'
  }
  io analytics 'Google<br/>Analytics'

  client -> server 'Request /' ''
  server -> logs 'Log' 'User IP'
  server -> client 'Resp' 'Profile'
  client -> analytics 'Log' 'Nav'
}

~~~~{.dataflow format=dfd}
%DATAFLOW%
~~~~

~~~~{.dataflow format=seq}
%DATAFLOW%
~~~~

Some of the charts from https://developers.google.com/chart/ have been implemented.

This plugin requires phantomjs to be installed on your system.

All the charts have some optional arguments in common

• size
  • default 700x700
• height
  • height of the chart, defaults to 700
• width
  • width of the chart, defaults to 700
• class
  • add to the class that the chart generates
  • initial class is named after the chart type (timeline, barchart, sankey etc)

Timeline charts are useful for project management, as an alternative to gantt charts

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

The timeline content consists of rows of lines with a task name, a task item, start and end times. Optionally a #color note at the end of the line (HTML color name or triplet) will set the color of the bar.

Dates should be in yyyy-mm-dd format.

Task1, hello,   1989-03-29, 1997-02-03 #green
Task1, sample,   1995-03-29, 2007-02-03   #663399
Task1, goodbye,   2019-03-29, 2027-02-03 #plum
Task2, eat and eat and eat and eat,  1997-02-03,  2001-02-03 #thistle
Task2, drink,  1998-02-03,  2004-02-03 #grey
Task3, shop,  2001-02-03,  2009-02-03 #red
Task3, drop,  2001-02-03,  2019-02-03 #darkorange

We will set some data into a buffer for ease of use

~~~~{.buffer to_buffer=timeline}
Task1, hello,   1989-03-29, 1997-02-03 #green
Task1, sample,   1995-03-29, 2007-02-03   #663399
Task1, goodbye,   2019-03-29, 2027-02-03 #plum
Task2, eat and eat and eat and eat,  1997-02-03,  2001-02-03 #thistle
Task2, drink,  1998-02-03,  2004-02-03 #grey
Task3, shop,  2001-02-03,  2009-02-03 #red
Task3, drop,  2001-02-03,  2019-02-03 #darkorange
~~~~

~~~~{.timeline
  from_buffer=timeline
  size=350x300}
~~~~

~~~~{.timeline from_buffer=timeline
background='GhostWhite'
size=350x300}
~~~~

~~~~{.timeline from_buffer=timeline
  background='none'
  labels=false
  size=350x300}
~~~~

Gantt charts are useful for project management.

The optional arguments are

• title
  • used as the generated images 'alt' argument
• size
  • size of image, widthxheight
• width
  • just constrain the width
• height
  • just constrain the height

• class
  • add this class to the image

The gantt content consists of rows of lines with a task id, a task name, a task group, start and end times and optionally dependencies and percent completed.

Dates should be in yyyy-mm-dd format.

1, count, Sums, 2015-10-28, 2015-10-29
2, add one, Summs, 2015-10-29, 2015-10-30, 1
3, add two, Sums, 2015-11-01, 2015-11-03, "1,2"
4, Overall, Website, 2015-10-20, 2015-10-29, , 23
5, route /index, Website, 2015-10-23, 2015-10-24
6, route /help, Website, 2015-10-20, 2015-10-22, , 100
7, route /about, Website, 2015-10-24, 2015-10-29, 5, 30

We will set some data into a buffer for ease of use

~~~~{.buffer to_buffer=gantt}
%GANTT%
~~~~

~~~~{.gantt
  from_buffer=gantt
  size=350x300}
~~~~

From google charts: A sankey diagram is a visualization used to depict a flow from one set of values to another. The things being connected are called nodes and the connections are called links. Sankeys are best used when you want to show a many-to-many mapping between two domains (e.g., universities and majors) or multiple paths through a set of stages (for instance, Google Analytics uses sankeys to show how traffic flows from pages to other pages on your web site).

For the curious, they're named after Captain Sankey, who created a diagram of steam engine efficiency that used arrows having widths proportional to heat loss.

The optional arguments are

• colors
  • comma separated list of HTML color names (or triplets), to be used for the nodes and links
• mode
  • how the link color is chosen
  • source - link color is the same as the source node
  • target - link color is the same as the target node
  • gradient - link color starts as node color and ends as target color

A | X | 5
A | Y | 7
A | Z | 6
B | X | 2
B | Y | 9
B | Z | 4

~~~~{.sankey width=90%
  mode=target}
%SANKEY_SIMPLE%
~~~~

~~~~{.sankey width=90%}
Brazil | Portugal | 5
Brazil | France | 1
Brazil | Spain | 1
Brazil | England | 1
Canada | Portugal | 1
Canada | France | 5
Canada | England | 1
Mexico | Portugal | 1
Mexico | England | 1
USA ,|Portugal | 1
Portugal | Angola | 2

...
~~~~

Conversion of some smilies to icons.

A small set of smilies are converted to UTF-8 characters, which can be tricky to show as not all fontsets support these.

Basic text smilies are handled, however there is also a range of smilies that are also available as words pre/post fixed with a colon, e.g. ::word::. Some of these will generate fontawesome icons and some will be picked from the very extensive [Emoji Cheatsheet], check this latter link for the full list of emoji words supported. Note that some of these may result, when generating PDFs, emoji's that do not display, trial and error is key!

smilie      {=}| word
<3          {=}| \:heart\:
:)          {=}| \:smile\:
:D or :grin:       {=}| \:grin\:
8-) or :cool:      {=}| \:cool\:
:P or :tongue:     {=}| \:tongue\:
:'( or :cry:       {=}| \:cry\:
:(  or :sad:       {=}| \:sad\:
;)  or :wink:      {=}| \:wink\:
:fear: or :fearful:{=}| \:fear\: or \:fearful\:
:halo: or :angel:  {=}| \:halo\: or \:angel\:
:devil: or :imp:   {=}| \:devil\: or \:imp\:
(c)         {=}| \:c\:, \:copyright\:
(r)         {=}| \:r\:, \:registered\:
(tm)        {=}| \:tm\:, \:trademark\:
:email:     {=}| \:email\:
:yes:       {=}| \:yes\:
:no:        {=}| \:no\:
:beer:      {=}| \:beer\:
:wine:      {=}| \:wine\:, \:glass\:
:cake:      {=}| \:cake\:
:star:      {=}| \:star\:
:ok:        {=}| \:ok\:, \:thumbsup\:
:bad:       {=}| \:bad\:, \:thumbsdown\:
:ghost:     {=}| \:ghost\:
:skull:     {=}| \:skull\:
:hourglass: {=}| \:hourglass\:
:time:      {=}| \:watch\:, \:clock\:
:sleep:     {=}| \:sleep\:
:zzz:       {=}| \:zzz\:, \:snooze\:
:dm:        {=}| \:dm\:, dangermouse!
:snowman:   {=}| \:snowman\:
:cancer:     {=}| \:cancer\:

Some unicodes only work when viewed via a browser and would not appear if the HTML is converted to PDF, so images are used as replacements.

Code    | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | A | B | C | D | E | F
U+1F60x | 😀 | 😁 | 😂 | 😃 | 😄 | 😅 | 😆 | 😇 | 😈 | 😉 | 😊 | 😋 | 😌 | 😍 | 😎 | 😏
U+1F61x | 😐 | 😑 | 😒 | 😓 | 😔 | 😕 | 😖 | 😗 | 😘 | 😙 | 😚 | 😛 | 😜 | 😝 | 😞 | 😟
U+1F62x | 😠 | 😡 | 😢 | 😣 | 😤 | 😥 | 😦 | 😧 | 😨 | 😩 | 😪 | 😫 | 😬 | 😭 | 😮 | 😯
U+1F63x | 😰 | 😱 | 😲 | 😳 | 😴 | 😵 | 😶 | 😷 | 😸 | 😹 | 😺 | 😻 | 😼 | 😽 | 😾 | 😿
U+1F64x | 🙀 | 🙁 | 🙂 | 🙃 | 🙄 | 🙅 | 🙆 | 🙇 | 🙈 | 🙉 | 🙊 | 🙋 | 🙌 | 🙍 | 🙎 | 🙏

Included in the distribution is a script to make use of all of the above code-blocks to alter [Markdown] into nicely formatted documents.

Here is the help

$ ct2 --help

Syntax: ct2 [options] filename

About:  Convert my modified markdown text files into other formats, by
    default will create HTML in same directory as the input file, will only
    process .md files.
    If there is no output option used the output will be to file of same
    name
    as the input filename but with an extension (if provided) from the
    document, use format: keyword (pdf html doc).

[options]
    -h, -?, --help        Show help
    -c, --clean           Clean up the cache before use
    converting to doc/odt
    -o, --output          Filename to store the output as, extension will
    control conversion
    -p, --prince          Convert to PDF using princexml, rather than pandoc
    --templates           list available templates
    -t, --template        name of template to use
    -v, --verbose         verbose mode
    -w, --wkhtmltopdf     Convert to PDF using wkhtmltopdf

On the first time you run ct2 a default template will be created in ~/.ct2/templates/default/template.html, a config file to accompany this will be created in ~/.ct2/templates/default/template.html

Create new templates in ~/.ct2/templates, one directory for each template, follow the example in the default directory.

If you are using [PrinceXML], remember that it is only free for non-commercial use, it also adds a purple P to the top right of the first page of your document, though this does not appear when you print out the document.