Permalink
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" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<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>
</head>
<body>
<div id="header">
<h1 class="title">Embedded diagrams in pandoc's markdown</h1>
<h3 class="author">Jakob Voss</h3>
</div>
<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="http://johnmacfarlane.net/pandoc/"><code class="url">http://johnmacfarlane.net/pandoc/</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?! -->
<dl>
<dt>ditaa</dt>
<dd><p>a java program created by Stathis Sideris to convert diagrams in ASCII art to PNG images. It is available at <a href="http://ditaa.sourceforge.net/"><code class="url">http://ditaa.sourceforge.net/</code></a>. Mikael Brännström created an extension to convert diagrams to EPS, available at <a href="http://ditaa-addons.sourceforge.net/"><code class="url">http://ditaa-addons.sourceforge.net/</code></a>.</p>
</dd>
<dt>dot</dt>
<dd><p>GraphViz's graph description language. See <a href="http://en.wikipedia.org/wiki/DOT_language"><code class="url">http://en.wikipedia.org/wiki/DOT_language</code></a> for more information.</p>
</dd>
<dt>rdfdot</dt>
<dd><p>RDF graphs based on RDF/Turtle. The command line program <code>rdfdot</code> is included in the CPAN package <a href="http://search.cpan.org/perldoc?RDF::Trine::Exporter::GraphViz">RDF::Trine::Exporter::GraphViz</a>.</p>
</dd>
</dl>
<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 README.md | pandoc -s -t html &gt; README.html
</code></pre>
<p>Or to create PDF:</p>
<pre><code>./mddia -pdf README.md | markdown2pdf -o README.pdf
</code></pre>
<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 |
+------------------+
~~~~~
</code></pre>
<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}
</code></pre>
<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;http://xmlns.com/foaf/0.1/&gt; .
@base &lt;http://example.com/&gt; .
&lt;alice&gt; foaf:name &quot;Alice&quot; ;
foaf:knows [ foaf:name &quot;Bob&quot; ] .
~~~~
</code></pre>
<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="https://github.com/nichtich/ditaa-markdown"><code class="url">https://github.com/nichtich/ditaa-markdown</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 README.md.</p>
<div class="footnotes">
<hr />
<ol>
<li id="fn1"><p>A better implementation would be based on pandoc's scripting API: <a href="http://johnmacfarlane.net/pandoc/scripting.html"><code class="url">http://johnmacfarlane.net/pandoc/scripting.html</code></a>. See the dot plugin at <a href="http://gitit.net/"><code class="url">http://gitit.net/</code></a> for how to dot it. <a href="#fnref1" class="footnoteBackLink">↩</a></p></li>
</ol>
</div>
</body>
</html>