Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
87 lines (83 sloc) 5.47 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns="">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />
<meta name="author" content="Jakob Voss" />
<title>Embedded diagrams in pandoc's markdown</title>
<div id="header">
<h1 class="title">Embedded diagrams in pandoc's markdown</h1>
<h3 class="author">Jakob Voss</h3>
<h1 id="introduction">Introduction</h1>
<p><strong>Pandoc</strong> is a Haskell program to convert between numerous document markup formats. It comes with an abstract document model and a serialization in extended markdown syntax. Pandoc was created by John MacFarlane and it is available as Open Source at <a href=""><code class="url"></code></a>.</p>
<p><strong>mddia</strong> is a simple, dirty Perl script to preprocess and convert diagrams embedded in pandoc's markdown syntax. This is a temporary hack because of lacking Haskell skills. Anyway, the script may be rewritten, but the underlying principles and data format will stay.<sup><a href="#fn1" class="footnoteRef" id="fnref1">1</a></sup> Up to now the script supports the following diagram types:</p>
<!-- TODO: Percent characters in URLs break PDF generation?! -->
<dd><p>a java program created by Stathis Sideris to convert diagrams in ASCII art to PNG images. It is available at <a href=""><code class="url"></code></a>. Mikael Brännström created an extension to convert diagrams to EPS, available at <a href=""><code class="url"></code></a>.</p>
<dd><p>GraphViz's graph description language. See <a href=""><code class="url"></code></a> for more information.</p>
<dd><p>RDF graphs based on RDF/Turtle. The command line program <code>rdfdot</code> is included in the CPAN package <a href="">RDF::Trine::Exporter::GraphViz</a>.</p>
<p>Ditaa is bundled with this script, while GraphViz and rdfdot must be installed manually. This script, pandoc, ditaa, dot, and rdfdot are all licensed as free software.</p>
<h1 id="usage">Usage</h1>
<p>mddia acts acts as filter that makes use of diagram creation programs to process a markdown source while emitting some image files.</p>
<p><img src="image-1.png" /> </p>
<p>Image files can be emitted in PNG format (the default) or in PDF format. You can choose the image format by command line option <code>-pdf</code> or <code>-png</code>. To create HTML from markdown via pandoc, call for instance:</p>
<pre><code>./mddia | pandoc -s -t html &gt; README.html
<p>Or to create PDF:</p>
<pre><code>./mddia -pdf | markdown2pdf -o README.pdf
<p>Diagrams are embedded in Markdown as source code blocks. This way your documents are valid and processable even without <code>mddia</code> (your diagrams will only show up as source code). For instance the image above was created with this code block:</p>
<pre><code>~~~~~ {.ditaa .no-separation}
+-----------------+ +--------+ +--------------------+
| markdown source |------&gt;| mdddia |------*---&gt;| processed markdown |
+-----------------+ +--------+ | +--------------------+
| \---&gt;| image files |
+------------------+ +--------------------+
| diagram creation |
| ditaa/dot/rdfdot |
<p>All &quot;class names&quot; (the strings starting with a dot) after the diagram type are passed are argument to the diagram creation. For instance</p>
<pre><code>~~~~~ {.ditaa .no-shadows .scale:0.4}
<p>Is passed to <code>ditaa</code> as <code>--no-shadows --scale 0.4</code>.</p>
<h1 id="examples">Examples</h1>
<h2 id="input-source-code">Input source code</h2>
<pre><code>~~~~ {.dot .Grankdir:LR}
digraph {
A -&gt; B -&gt; C;
A -&gt; C;
~~~~ {.rdfdot}
@prefix foaf: &lt;; .
@base &lt;; .
&lt;alice&gt; foaf:name &quot;Alice&quot; ;
foaf:knows [ foaf:name &quot;Bob&quot; ] .
<h2 id="generated-diagrams">Generated diagrams</h2>
<p><img src="image-2.png" /> </p>
<p><img src="image-3.png" /> </p>
<h1 id="about">About</h1>
<p>mddia is available at <a href=""><code class="url"></code></a>. Feel free to fork and extend under any free viral open source license. The files README.html and README.pdf in the repository may be out of date compared to the original</p>
<div class="footnotes">
<hr />
<li id="fn1"><p>A better implementation would be based on pandoc's scripting API: <a href=""><code class="url"></code></a>. See the dot plugin at <a href=""><code class="url"></code></a> for how to dot it. <a href="#fnref1" class="footnoteBackLink">↩</a></p></li>