title: Using App::Basis::ConvertText2 format: pdf author: Kevin Mulholland keywords: perl, readme, markdown template: default date: 2017-02-28 version: 8

Introduction

If you are reading this document as a markdown document you may want to try [README PDF] as an alternative. This have been generated from this file and the software provided by this distribution.

This is a perl module and a script that makes use of %TITLE%

This is a wrapper for [pandoc] implementing extra fenced code-blocks to allow the creation of charts and graphs etc. Documents may be created a variety of formats. If you want to create nice PDFs then it can use [PrinceXML] to generate great looking PDFs or you can use [wkhtmltopdf] to create PDFs that are almost as good, the default is to use pandoc which, for me, does not work as well.

HTML templates can also be used to control the layout of your documents.

The fenced code block handlers are implemented as plugins and it is a simple process to add new ones.

There are plugins to handle

• ditaa
• mscgen
• graphviz
• uml
• gnuplot
• gle
• sparklines
• charts
• barcodes and qrcodes
• and many, many others

As a perl module you can obtain it from https://metacpan.org/pod/App::Basis::ConvertText2 or install

cpanm App::Basis::ConvertText2

Alternatively it is available from https://github.com/27escape/App-Basis-ConvertText2

You will then be able to use the ct2 script to process files

If you are reading this document in PDF form, then note that all the images are created by the various plugins and included in the output, there is no store of pre-built images. That you can read this proves the plugins all work!

Most of the chapters are based around the various plugins that are available and the commands that they expose.

Document header and variables

If you are just creating simple things, then you do not need a document header, but to make full use of the templating system, having header information is vital.

Example
title: App::Basis::ConvertText2 format: pdf date: 2014-05-12 author: Kevin Mulholland keywords: perl, readme template: coverpage version: 5

As you can see, we use a series of key value pairs separated with a colon. The keys may be anything you like, except for the following which have special significance.

• format shows what output format we should default to.
• template shows which template we should use

The keys may be used as variables in your document or in the template, by upper-casing and prefixing and postfixing percent symbols '%'

Example
version as a variable %VERSION%

If you want to display the name of a variable without it being interpreted, prefix it with a backslash '', this will be removed in the final document.

Example	Output
%TITLE%	%TITLE%

Gotchas about variables

• Variables used within the content area of a code-block will be evaluated before processing that block, if a variable has not yet been defined or saved to a buffer then it will only be evaluated at the end of document processing, so output may not be as expected.
• Variables used in markdown tables may not do what you expect if the variable is multi-line.

Table of contents

As documents are processed, the HTML headers (H2..H6) are collected together to make a table of contents. This can be used either in your template or document using the TOC variable.

Example
%TOdC%

The built table of contents is at the top of this document.

Note that if using a TOC, then the HTML headers are changed to have a number prefixed to them, this helps ensure that all the TOC references are unique.

Skipping header {.toc_skip}

If you do not want an item added to the toc add the class 'toc_skip' to the header (or skiptoc)

Example
### Skipping header {.toc_skip}

Hopefully you can see that the header for this section is not in the TOC

This feature is disabled at the moment while bugs are fixed.

Admonitions

There are certain statements that you may want to draw attention to by taking them out of the content’s flow and labeling them with a priority. These are called admonitions. It’s rendered style is determined by the assigned label (i.e., value). We provide twelve admonition style labels:

• NOTE
• INFO
• TIP
• IMPORTANT
• CAUTION
• WARNING
• DANGER
• TODO
• ASIDE
• QUESTION
• FIXME
• ERROR

When you want to call attention to a single paragraph, start the first line of the paragraph with the label you want to use. The label must be uppercase and followed by a colon ':'

WARNING: Something could go wrong if you do not follow the rules

• The label must be uppercase and immediately followed by a colon ':'
• Separate the first line of the paragraph from the label by a single space.
• Title is the name of the admonition, unless specified - see below

And here is the generated Admonition

WARNING: Something could go wrong if you do not follow the rules

Titles may be included in admonitions, add them in within brackets, note that there are no spaces between the admonition name and the colon.

NOTE(title for note): Something could go wrong if you do not follow the rules

And here is an example with a title

NOTE(title for note): Something could go wrong if you do not follow the rules

All the Admonitions have associated icons.

Normal Markup may be used in the paragraph.

Admonitions are processed before the rest of the document, so you cannot put their contents into buffers and expect them to work correctly.

Admonitions are a short cut to Admonition Boxes which allow multiple paragraphs to be used.

Font Awesome

Font Awesome provides many useful icons,see [Font Awesome Cheatsheet], however there is a lot of hassle to add them to your document; we of course offer a simple shortcut, with the form

\:fa:font-name

E.g.

\:fa:trash

Will display a :fa:trash icon.

NOTE: We do not use the preceding 'fa-' in the name as Font Awesome does.

So 'trash' rather than 'fa-trash'.

It is possible to scale the images, give them colors and apply CSS classes to them by adding this information in square brackets

E.g.

\:fa:trash:[2x]

The options are

• size [lg], [2x], [3x], [4x], [5x]
  • :fa:trash:[lg] :fa:trash:[2x], :fa:trash:[3x], :fa:trash:[4x], :fa:trash:[5x].
• foreground color [#red]
  • :fa:trash:[2x #red]
• foreground and background color [#yellow.black]
  • :fa:trash:[2x #yellow.black]
• rotate [90], [180], [270]
  • :fa:flask:[2x 90], :fa:flask:[2x 180], :fa:flask:[2x 270]
• flip vertical [flipv]
  • :fa:flask:[2x] vs :fa:flask:[2x flipv]
• flip horizontal [fliph]
  • :fa:graduation-cap:[2x] vs :fa:graduation-cap:[2x fliph]
• fixed width [fw]
  • :fa:gamepad:[2x]. vs :fa:gamepad:[2x fw].
  • note the normal font (left) has a smaller space before the '.' than the fixed width font (right)
• border [border]
  • :fa⚙️[ border]

Any thing remaining in the square brackets after handling the above options will be considered as a class to be applied to the icon.

Of course multiple options may be combined

\:fa:trash:[2x 90 #red border]

as :fa:trash:[2x 90 #red border]

Google Material Icons

Google also provides many useful icons,see [Google Material Font Cheatsheet], however there is a lot of hassle to add them to your document; we of course offer a simple shortcut, with the form

\:mi:font-name

E.g.

\:mi:add-shopping-cart

Will display a :mi:add-shopping-cart icon.

NOTE: Google Material fonts do not usually have a '-' in them, we use this to allow us to know where the font name ends. It is removed.

It is possible to scale the images, give them colors and apply CSS classes to them by adding this information in square brackets

E.g.

\:mi:alarm:[2x]

The options are

• size [lg] [2x], [3x], [4x], [5x]
  • :mi:alarm:[lg] :mi:alarm:[2x], :mi:alarm:[3x], :mi:alarm:[4x], :mi:alarm:[5x]
• rotate [90], [180], [270]
  • :mi📖[2x 90], :mi📖[2x 180], :mi📖[2x 270 ]
• flip vertical [flipv]
  • :mi:build:[2x] vs :mi:build:[2x flipv]
• flip horizontal [fliph]
  • :mi:add-shopping-cart:[2x] vs :mi:add-shopping-cart:[2x fliph]
• foreground color [#orangea700]
  • :mi📖[2x #orangea700]
• foreground and background color [#yellow.black]
  • :mi📖[2x #yellow.black]

Any thing remaining in the square brackets after handling the above options will be considered as a class to be applied to the icon.

Of course multiple options may be combined

\:mi:delete:[2x 90 #red border-inset-grey]

as :mi:delete:[2x 90 #red border-inset-grey]

All of the google material colors are available to be used both in css and style sections.

Orange with an accent of A700, is named as orangea700. Light blue 500 is lightblue500.

Anywhere in your document/css that uses color= or color: then these replacements can be made.

For the complete list of colors see [Google Colors]

Default Icons

It is possible to specify icons without type, however this is currently defaulting to Material Icons, until a third option is found, like the github set.

\:cake: should show a :cake:

Including other files

It is possible to include content from other files, the methods match fenced code-block and their short cuts.

The optional arguments are

• class
  • add a div with this CSS class name
• style
  • add a div with this CSS style
• markdown
  • import file is markdown and will need some tidying up
• headings
  • if a markdown file, add this nunber of '#' characters to headers in the imported file
• date
  • add the date the import file was updated to the end of the imported text

import can also be used as a synonym for include.

Example
\{\{.include file="filename"}} ~~~~{.include file='filename'} ~~~~

Either of these methods will bring the contents of the file inline to the current document at the location where they are used.

Font effects

Markdown does not include any facility for setting the maniulating the font of text in a document, however sometimes it is useful to be able to do some basic manipulation.

We have a HTML-like constructs

• For Underline - standard HTML
  • <u> Your text </u>
• For Strikethroughs - standard HTML
  • <s> Your text </s>
• For Colors
  • <c:colorname> Your text </c>
  • <c:#foreground.background> Your text </c>

Example	Output
<c\:red>set this string to red</c> <c\:#white.blue>White foreground, blue background</c> <c\:#.green300>green300 background</c>	<c:red>set this string to red <c:#white.blue>White foreground, blue background <c:#.green300>green300 background

Fenced code-blocks

A fenced code-block is a way of showing that some text needs to be handled differently. Often this is used to allow markdown systems (and [pandoc] is no exception) to highlight program code.

code-blocks take the form

Example
~~~~{.tag argument1='fred' arg2=3} contents ... ~~~~

Code-blocks ALWAYS start at the start of a line without any preceding whitespace. The 'top' line of the code-block can wrap onto subsequent lines, this line is considered complete when the final '}' is seen. There should be only whitespace after the closing '}' symbol before the next line.

We use this construct to create our own handlers to generate HTML or markdown.

Note that only code-blocks described in this documentation have special handlers and can make use of extra features such as buffering.

If using [pandoc] then you can take advantage of the code blocks for code syntax highlighting

Example
~~~~{.perl} sub process { my $self = shift ; my ( $tag, $content, $params, $cachedir ) = @_ ; # 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 ) ; } ~~~~
Output
~~~~{.perl} sub process { my $self = shift ; my ( $tag, $content, $params, $cachedir ) = @_ ; # 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 Example ~~~~{.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} Example ~~~~{.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. Example %SPARK_DATA% has content %SPARK_DATA% %GREENSPARK% has a generated image %GREENSPARK% Buffering also allows us to add content into markdown constructs like bullets. Example Output * %SPARK_DATA% * %GREENSPARK% * %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 ~~~~ Text The text plugin has lots of simple handlers, they all output text/HTML. Yamlasjson 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 Example Output ~~~~{.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 ~~~~ ~~~~{.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 ~~~~ Yamlasxml 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. Example Output ~~~~{.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 ~~~~ ~~~~{.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 ~~~~ Table 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 Example ~~~~{.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% ~~~~ Output The table can be sorted too, reverse date (newest first) Table cells can contain extra information to color the cell and provide alignment. This information needs to be enclosed in braces '{}' and be the last data in the cell #foreground set the foreground color only eg #red red text on a default background #foreground.background set the foreground and background color eg #white.red white text on a red background '=' align: center '<' align: left '>' align: right '^' vertical align top '-' vertical-align middle '_' vertical-align bottom '30px' set the width of a cell to 30px, obviously this can be any numerical value '50%' set the width of a cell to 50%, obviously this can be any numerical value between 0 and 100 c2 - column span a number of columns, 2 in this case Currently the color needs to be the last thing in the braces for things to work properly {=- #white.red} center white text on a red background vertically and horizontally Spreadsheet 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. Example ~~~~{.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% ~~~~ Output The spreadsheet can be sorted too, reverse date (newest first) Links 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 | http://johnmacfarlane.net/pandoc PrinceXML | http://www.princexml.com Markdown | http://daringfireball.net/projects/markdown msc | http://www.mcternan.me.uk/mscgen/ ditaa | http://ditaa.sourceforge.net PlantUML | http://plantuml.sourceforge.net Salt | http://plantuml.sourceforge.net/salt.html graphviz | http://graphviz.org JSON | https://en.wikipedia.org/wiki/Json YAML | https://en.wikipedia.org/wiki/Yaml wkhtmltopdf | http://wkhtmltopdf.org/ My Github | https://github.com/27escape/App-Basis-ConvertText2/tree/master/scripts Brewer | http://www.graphviz.org/content/color-names#brewer README PDF | https://github.com/27escape/App-Basis-ConvertText2/blob/master/docs/README.pdf Font Awesome Cheatsheet | http://fontawesome.io/cheatsheet/ Google Material Font Cheatsheet | https://www.google.com/design/icons/ Google Colors | http://www.google.com/design/spec/style/color.html#color-color-palette Emoji Cheatsheet | http://www.emoji-cheat-sheet.com Example ~~~~{.links class='weblinks' } %WEBLINKS% ~~~~ Output ~~~~{.links class='weblinks' from_buffer=weblinks} ~~~~ Version 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 Example Output ~~~~{.version} %VERSIONTABLE% ~~~~ ~~~~{.version width='45%' from_buffer=versiontable} ~~~~ Page 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 Example This is start a new page, again using short block form. \{\{.page}} as will this ---- Output will not be shown as it will mess up the document! Columns 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&amp;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. Example ~~~~{.columns count=3 ruler=yes width='95%'} %COLUMNS% ~~~~ Output ~~~~{.columns from_buffer=columns count=3 ruler=yes width='95%'} ~~~~ Appendix 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. Example Output * \{\{.appendix}} * \{\{.appendix}} * \{\{.appendix}} * {{.appendix}} * {{.appendix}} * {{.appendix}} Counter 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' Example Output * \{\{.counter name=fred}} * \{\{.counter name=fred}} * default \{\{.counter}} * \{\{.counter name=martha start=100}} * \{\{.counter name=martha}} * {{.counter name=fred}} * {{.counter name=fred}} * default {{.counter}} * {{.counter name=martha start=100}} * {{.counter name=martha}} Comment 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. Example Output Normal flow of text ~~~~\{.comment} This comment is not seen in the generated document ~~~~ text continues Normal flow of text This comment is not seen in the generated document text continues Indent 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 Example Here is the example config file \{\{.indent file=fred.conf style='background-color:grey50;'}} text continues Percent 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 Example Output * \{\{.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}} default color {{.percent value=90 border=1}} {{.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}} Tree 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 -. Example Output ~~~~{.tree} * one * 1.1 * two * two point 1 * 2.2 * three * 3.1 * 3.2 * three point 3 * four * five * six * 3 . seven ~~~~ ~~~~{.tree} * one * 1.1 * two * two point 1 * 2.2 * three * 3.1 * 3.2 * three point 3 * four * five * six * 3 . seven ~~~~ Badges 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 Example A basic badge ~~~~{.badge subject='test run' status='completed' color='green'} ~~~~ Badges / shields work well as short blocks \{\{.shield subject='test run' status='pending' size='150'}} Swap the subject and status around \{\{.shield subject='test run' status='pending' size='150' color='orange' reverse=1}} Fully specify the colors \{\{.shield subject='test run' status='failed' size='150' color='#white.red' }} Output {{.badge subject='test run' status='completed' color='green'}} Badges / shields work well as short blocks {{.shield subject='test run' status='pending' size='150'}} Swap the subject and status around {{.shield subject='test run' status='pending' size='150' color='orange' reverse=1}} Fully specify the colors {{.shield subject='test run' status='failed' size='150' color='#white.red' }} Buttons 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' Example A basic button ~~~~{.button subject='test run' color='green'} ~~~~ Buttons work well as short blocks \{\{.button subject='test run' size='150'}} Fully specify the colors \{\{.button subject='test run' size='150' color='#blue.yellow' }} With a border \{\{.button subject='test run' border='1' }} and a colored border \{\{.button subject='test run' border='red' }} With an icon \{\{.button subject='test run' icon='plus-circle' color='green'}} Using a Material icon \{\{.button subject='Upload' icon='\:mi:file-upload' }} Output {{.button subject='test run' color='green'}} Buttons work well as short blocks {{.button subject='test run' size='150'}} Fully specify the colors {{.button subject='test run' size='150' color='#blue.yellow' }} With a border {{.button subject='test run' border='1' }} and a colored border {{.button subject='test run' border='red' }} With an icon {{.button subject='test run' icon='plus-circle' color='green'}} Using a Material icon {{.button subject='Upload' icon=':mi:file-upload'}} Box 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. Example Output ~~~~{.box from_buffer=box title='Important Notice' width='80%'} ~~~~ {{.box from_buffer=box title='Important Notice' width='80%'}} Admonition Boxes 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. Examples {{.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' }} Glossary 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. Example This is a \{\{.gloss abbr='SMPL' def='short spelling of SAMPLE'}}. There are other things we can do \{\{.glossary abbr='test' define='Test long form and arguments'}}. You can also use the word *term* as a synonymn of *abbr*. 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}} Output This is a {{.gloss abbr='SMPL' def='short spelling of SAMPLE'}}. There are other things we can do {{.glossary abbr='test' define='Test long form and arguments'}}. You can also use the word *term* as a synonymn of *abbr*. Optionally if there is a link to a item in 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 an 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'}} Quote 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 Example Output ~~~~{.quote title='Title' width=100%} %QUOTE% ~~~~ {{.quote from_buffer=quote title='Title' width=100%}} Or without the title ~~~~{.quote title='Title' width=350px} %QUOTE% ~~~~ {{.quote from_buffer=quote width=350px}} Sparklines 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 Example Output ~~~~{.buffer to_buffer='spark_data'} %SPARK_DATA% ~~~~ here is a standard sparkline ~~~~{.sparkline title='basic sparkline'} %SPARK_DATA% ~~~~ Draw the sparkline using buffered data ~~~~{.sparkline title='blue sparkline' scheme='blue' from_buffer='spark_data'} ~~~~ ~~~~{.sparkline title='blue sparkline' scheme='blue' from_buffer='spark_data'} ~~~~ Charts 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 ~~~~ Example Output Pie Chart ~~~~{.chart format='pie' title='Pie' from_buffer='chart_data' size='300x300'} ~~~~ ~~~~{.chart format='pie' title='Pie' from_buffer='chart_data' size='300x300' } ~~~~ Bar Chart ~~~~{.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='bars' title='Bars' from_buffer='chart_data' size='300x300' xaxis='things ways' yaxis='Vertical things' legends='A,B,C,D,E,F,G,H' } ~~~~ Mixed Chart ~~~~{.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' } ~~~~ ~~~~{.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' } ~~~~ mscgen 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"]; } Example Output ~~~~{.mscgen title="mscgen1" width=350} %MSCGEN% ~~~~ ~~~~{.mscgen title="mscgen1" width=350 from_buffer=mscgen} ~~~~ UML Diagrams 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 Example Output ~~~~{.uml width=350} %UML% ~~~~ ~~~~{.uml from_buffer=uml width=350} ~~~~ Salt [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 Example Output ~~~~{.uml width=350} %SALT% ~~~~ ~~~~{.uml from_buffer=salt width=350} ~~~~ Sudoku Plantuml can generate random sudoku patterns Example Output ~~~~{.uml width=350} sudoku ~~~~ ~~~~{.uml width=350} sudoku ~~~~ To always generate the same pattern, append a seed value after 'sudoku' ~~~~{.uml} sudoku 45azkdf4sqq ~~~~ Umltree 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 Example Output ~~~~{.umltree width=350} %UMLTREE% ~~~~ ~~~~{.umltree from_buffer=umltree width=350} ~~~~ Ditaa 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 Example Output ~~~~{.ditaa width=350} %DITAA% ~~~~ ~~~~{.ditaa from_buffer=ditaa width=350} ~~~~ Graphviz [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]; } Example Output ~~~~{.graphviz title="graphviz1" size=width=350} %GRAPHVIZ% ~~~~ ~~~~{.graphviz title="graphviz1" width=350 from_buffer=graphviz} ~~~~ Mindmap 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 Example Output ~~~~{.mindmap size=350x250} %MINDMAP% ~~~~ {{.mindmap from_buffer='mindmap' size='350x250'}} Change the node style and the color scheme. ~~~~{.mindmap shapes='box' scheme=green size=350x250} %MINDMAP% ~~~~ {{.mindmap shapes='box' scheme=green from_buffer='mindmap' size=350x250}} Venn diagram 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! Example ~~~~{.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 ~~~~ Output ~~~~{.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 ~~~~ Barcodes 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 Example Output Code 39 ~~~~{.barcode type='code39'} 123456789 ~~~~ {{.barcode type='code39' content=123456789}} EAN8 ~~~~{.barcode type='ean8'} 12345678 ~~~~ {{.barcode type='ean8' content='12345678'}} IATA2of5 ~~~~{.barcode type='IATA2of5'} 12345678 ~~~~ {{.barcode type='IATA2of5' content='12345678'}} QR code 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 Example Output ~~~~{.qrcode } http://news.bbc.co.uk ~~~~ ~~~~{.qrcode } http://news.bbc.co.uk ~~~~ To change the size of the barcode ~~~~{.qrcode height='80'} http://news.bbc.co.uk ~~~~ ~~~~{.qrcode height='80'} http://news.bbc.co.uk ~~~~ To use version 1 Version 1 only allows 15 characters ~~~~{.qrcode height=60 version=1} smaller text.. ~~~~ ~~~~{.qrcode height=60 version=1} smaller text.. ~~~~ To change pixel size ~~~~{.qrcode pixels=5} smaller text.. ~~~~ ~~~~{.qrcode pixels=5} smaller text.. ~~~~ Gle / glx This is a complex graph/chart drawing package available from http://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" Example ~~~~{.gle} %GLE% ~~~~ Output ~~~~{.gle from_buffer=gle} ~~~~ Gnuplot This is the granddaddy of charting/plotting programs, available from http://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 Example ~~~~{.gnuplot} %GNUPLOT% ~~~~ Output {{.gnuplot from_buffer=gnuplot}} Ploticus 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. Example ~~~~{.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 ~~~~ Output // 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 And here is that timeline (from http://ploticus.sourceforge.net/gallery/clickmap_time2.htm) #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 Polaroid 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 Example Output ~~~~{.polaroid src='heartp.jpg' title='The heart of Paris' date='2015-02-06'} ~~~~ ~~~~{.polaroid src='heartp.jpg' title='The heart of Paris' date='2015-02-06'} ~~~~ Blockdiag Blockdiag provides a number of ways to create nice diagrams. See http://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 blockdiag 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; Example Output ~~~~{.blockdiag width=350} %BLOCKDIAG% ~~~~ ~~~~{.blockdiag from_buffer=blockdiag width=350} ~~~~ nwdiag 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; } Example Output ~~~~{.nwdiag width=350} %NWDIAG% ~~~~ ~~~~{.nwdiag from_buffer=nwdiag width=350 } ~~~~ packetdiag 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] Example Output ~~~~{.packetdiag width=350} %PACKETDIAG% ~~~~ {{.packetdiag from_buffer=packetdiag width=350}} rackdiag 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 Example Output ~~~~{.rackdiag width=350} %RACKDIAG% ~~~~ ~~~~{.rackdiag from_buffer=rackdiag width=350} ~~~~ actdiag The classic swim lanes. write -> convert -> image lane user { label = "User" write [label = "request"]; image [label = "done"]; } lane server { label = "Server" convert [label = "process"]; } Example Output ~~~~{.actdiag} %ACTDIAG% ~~~~ ~~~~{.actdiag from_buffer=actdiag width=350} ~~~~ seqdiag 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; Example Output ~~~~{.seqdiag} %SEQDIAG% ~~~~ ~~~~{.seqdiag from_buffer=seqdiag width=350} ~~~~ Dataflow 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' } Example Output Dataflow ~~~~{.dataflow format=dfd} %DATAFLOW% ~~~~ {{.dataflow format=dfd from_buffer=dataflow size=350x500}} As a sequence diagram ~~~~{.dataflow format=seq} %DATAFLOW% ~~~~ {{.dataflow format=seq from_buffer=dataflow size=350x500}} Google charts 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 chart 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 ~~~~ Example Output Default ~~~~{.timeline from_buffer=timeline size=350x300} ~~~~ ~~~~{.timeline from_buffer=timeline size=350x300} ~~~~ Setting a background color Use the 'background' parameter to set a color, this can be a HTML color name or hex triplet, 'none' or 'transparent' will remove the background. ~~~~{.timeline from_buffer=timeline background='GhostWhite' size=350x300} ~~~~ ~~~~{.timeline from_buffer=timeline background='honeydew' size=350x300} ~~~~ Removing bar labels This is useful if you only really want to show an approximation of how long things will take without specifying which tasks are which. Set the 'labels' parameter to 'false' or 0. ~~~~{.timeline from_buffer=timeline background='none' labels=false size=350x300} ~~~~ ~~~~{.timeline from_buffer=timeline background='none' labels=false size=350x300} ~~~~ Gantt 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% ~~~~ Example Output Default ~~~~{.gantt from_buffer=gantt size=350x300} ~~~~ ~~~~{.gantt from_buffer=gantt size=350x300} ~~~~ Sankey Chart 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 Example Output A Simple set ~~~~{.sankey width=90% mode=target} %SANKEY_SIMPLE% ~~~~ ~~~~{.sankey from_buffer=sankey_simple width=90%} ~~~~ A Complex set - only a small portion of the data is being shown ~~~~{.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 ... ~~~~ ~~~~{.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 | France | 1 Mexico | Spain | 5 Mexico | England | 1 USA | Portugal | 1 USA | France | 1 USA | Spain | 1 USA | England | 5 Portugal | Angola | 2 Portugal | Senegal | 1 Portugal | Morocco | 1 Portugal | South Africa | 3 France | Angola | 1 France | Senegal | 3 France | Mali | 3 France | Morocco | 3 France | South Africa | 1 Spain | Senegal | 1 Spain | Morocco | 3 Spain | South Africa | 1 England | Angola | 1 England | Senegal | 1 England | Morocco | 2 England | South Africa | 7 South Africa | China | 5 South Africa | India | 1 South Africa | Japan | 3 Angola | China | 5 Angola | India | 1 Angola | Japan | 3 Senegal | China | 5 Senegal | India | 1 Senegal | Japan | 3 Mali | China | 5 Mali | India | 1 Mali | Japan | 3 Morocco | China | 5 Morocco | India | 1 Morocco | Japan | 3 ~~~~ Smilies / Emoji's 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\: Unicode replacements 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 | 🙀 | 🙁 | 🙂 | 🙃 | 🙄 | 🙅 | 🙆 | 🙇 | 🙈 | 🙉 | 🙊 | 🙋 | 🙌 | 🙍 | 🙎 | 🙏 Using ct2 script to process files 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.