Jekyll2023-11-13T21:35:09+00:00http://simonvanderveldt.nl/feed.xmlSimon van der VeldtSimon van der VeldtGitHub Pages with GitHub Flavored Markdown, footnotes and syntax highlighting simplified2016-06-01T00:00:00+00:002016-06-01T00:00:00+00:00http://simonvanderveldt.nl/github-pages-with-github-flavored-markdown-footnotes-and-syntax-highlighting-simplified<p>Another update regarding the use of GitHub Flavored Markdown on GitHub Pages. GitHub Pages has <a href="https://github.blog/2016-02-01-github-pages-now-faster-and-simpler-with-jekyll-3-0/">updated its Jekyll version to 3.0</a> on the first of February 2016.<br />
This update includes a switch to <a href="https://kramdown.gettalong.org">kramdown</a> as its Markdown parser as well as only supporting <a href="http://kramdown.gettalong.org/syntax_highlighter/rouge.html">Rouge</a> as syntax highlighter. This means we’re effectively back to the <a href="/jekyll-github-flavored-markdown-and-footnotes">original setup from 2013</a> but because all of these components have received some updates in the meantime everything is now supported out of the box.</p>
<p>Support for other Markdown engines like <a href="https://github.com/vmg/redcarpet">Redcarpet</a> and <a href="https://github.com/davidfstr/rdiscount">RDiscount</a> was consecutively <a href="https://github.blog/2016-05-02-github-pages-drops-support-for-rdiscount-redcarpet-and-redcloth-textile-markup-engines/">dropped from GitHub Pages</a> on the second of May 2016.<br />
Some more information on this decision can be found in <a href="https://github.blog/2016-04-01-a-look-behind-our-decision-to-standardize-on-a-single-markdown-engine-for-github-pages/">this blogpost</a>.</p>
<h2 id="configuration">Configuration</h2>
<p>For basic functionality, including parsing of GitHub Flavored Markdown and support for footnotes and syntax highlighting using fenced code blocks no configuration is necessary.<br />
GitHub already takes care of all of this with its <a href="https://help.github.com/en/articles/configuring-jekyll">default configuration</a>.</p>
<h2 id="customization">Customization</h2>
<p>Any of the configuration options in the <a href="https://help.github.com/en/articles/configuring-jekyll#defaults-you-can-change">defaults you can change section</a> can be configured to your liking.<br />
Personally I prefer GitHub Flavored Markdown’s way of handling line breaks so I added the following to my configuration:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">kramdown</span><span class="pi">:</span>
<span class="na">hard_wrap</span><span class="pi">:</span> <span class="no">true</span>
</code></pre></div></div>Simon van der VeldtAnother update regarding the use of GitHub Flavored Markdown on GitHub Pages. GitHub Pages has updated its Jekyll version to 3.0 on the first of February 2016. This update includes a switch to kramdown as its Markdown parser as well as only supporting Rouge as syntax highlighter. This means we’re effectively back to the original setup from 2013 but because all of these components have received some updates in the meantime everything is now supported out of the box.Boot2docker on xhyve2015-06-15T00:00:00+00:002015-06-15T00:00:00+00:00http://simonvanderveldt.nl/boot2docker-on-xhyve<p class="alert alert-warning"><strong>Warning:</strong> This is all fairly new stuff, my machine locked up if I had run a Virtualbox machine prior to starting an xhyve machine. Don’t say I didn’t warn you ;)</p>
<p><a href="https://github.com/mist64/xhyve">Xhyve</a> is a new hypervisor in the vein of <a href="http://www.linux-kvm.org">KVM</a> on Linux and <a href="http://bhyve.org">bhyve</a> on BSD. It’s actually a <a href="https://github.com/mist64/xhyve#what-is-bhyve">port</a> of BSD’s bhyve to OS X.<br />
It’s more similar to KVM than to Virtualbox in that it’s minimal and commandline only which makes it a good fit for an always running virtual machine like boot2docker on OS X.<br />
This post documents the steps to get boot2docker running within xhyve and contains some quick benchmarks as well to compare xhyve’s performance with Virtualbox.</p>
<!--more-->
<h2 id="building-xhyve">Building xhyve</h2>
<p>Building xhyve is actually as simple as can be. As documented in xhyve’s <a href="http://www.pagetable.com/?p=831">introduction to the world</a> it’s only a matter of cloning the sources and issueing a <code class="language-plaintext highlighter-rouge">make</code>:</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">git clone https://github.com/mist64/xhyve
</span><span class="gp">$</span><span class="w"> </span><span class="nb">cd </span>xhyve
<span class="gp">$</span><span class="w"> </span>make
<span class="gp">$</span><span class="w"> </span>./build/xhyve <span class="nt">-h</span>
<span class="gp">Usage: xhyve [-behuwxACHPWY] [-c vcpus] [-g <gdb port></span><span class="o">]</span> <span class="o">[</span><span class="nt">-l</span> <lpc>]
<span class="c">...
</span></code></pre></div></div>
<h2 id="extract-the-boot2docker-kernel-and-initrd">Extract the boot2docker kernel and initrd</h2>
<p>Start by creating a directory named <code class="language-plaintext highlighter-rouge">boot2docker</code> inside the xhyve directory and making a copy of <code class="language-plaintext highlighter-rouge">xhyverun.sh</code> to use for boot2docker.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gp">$</span><span class="w"> </span><span class="nb">mkdir </span>boot2docker
<span class="gp">$</span><span class="w"> </span><span class="nb">cp </span>xhyverun.sh xhyve-boot2docker.sh
</code></pre></div></div>
<p>xhyve currently doesn’t come with a BIOS or EFI booter. This means it’s necessary to <a href="https://github.com/boot2docker/boot2docker/blob/f996284ecf003356e6d749394e95804dc62708e8/doc/AUTOMATED_SCRIPT.md#extracting-initrd-and-vmlinuz64">extract</a> the kernel and initrd from boot2docker and pass them to xhyve manually.</p>
<p>The simplest way to do so is to mount the boot2docker iso which can be found in <code class="language-plaintext highlighter-rouge">~/.boot2docker/boot2docker.iso</code> and then copying the <code class="language-plaintext highlighter-rouge">initrd.img</code> and <code class="language-plaintext highlighter-rouge">vmlinuz64</code> from the <code class="language-plaintext highlighter-rouge">boot</code> directory of the mounted volume to the <code class="language-plaintext highlighter-rouge">boot2docker</code> directory.</p>
<h2 id="prepare-the-xhyve-boot2dockersh-file">Prepare the xhyve-boot2docker.sh file</h2>
<p>Configurtion of the xhyve virtual machine is done through command line arguments. The <code class="language-plaintext highlighter-rouge">xhyverun.sh</code>/<code class="language-plaintext highlighter-rouge">xhyve-boot2docker.sh</code> shell scripts make this a bit easier and more transparent.<br />
To match the virtual machine <a href="https://github.com/boot2docker/boot2docker/blob/f996284ecf003356e6d749394e95804dc62708e8/doc/FAQ.md#what-are-the-specs-of-the-vm">specs from boot2docker</a> edit the <code class="language-plaintext highlighter-rouge">xhyve-boot2docker.sh</code> file so it reads like this:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">#!/bin/sh</span>
<span class="nv">KERNEL</span><span class="o">=</span><span class="s2">"boot2docker/vmlinuz64"</span>
<span class="nv">INITRD</span><span class="o">=</span><span class="s2">"boot2docker/initrd.img"</span>
<span class="nv">CMDLINE</span><span class="o">=</span><span class="s2">"loglevel=3 user=docker console=ttyS0 console=tty0 noembed nomodeset norestore waitusb=10:LABEL=boot2docker-data base"</span>
<span class="nv">MEM</span><span class="o">=</span><span class="s2">"-m 2G"</span>
<span class="nv">SMP</span><span class="o">=</span><span class="s2">"-c 8"</span>
<span class="nv">NET</span><span class="o">=</span><span class="s2">"-s 2:0,virtio-net,en0"</span>
<span class="nv">IMG_CD</span><span class="o">=</span><span class="s2">"-s 3,ahci-cd,boot2docker/boot2docker.iso"</span>
<span class="c">#IMG_HDD="-s 4,virtio-blk,/somepath/somefile.img"</span>
<span class="nv">PCI_DEV</span><span class="o">=</span><span class="s2">"-s 0:0,hostbridge -s 31,lpc"</span>
<span class="nv">LPC_DEV</span><span class="o">=</span><span class="s2">"-l com1,stdio"</span>
<span class="c">#UUID="-U deadbeef-dead-dead-dead-deaddeafbeef"</span>
build/xhyve <span class="nv">$MEM</span> <span class="nv">$SMP</span> <span class="nv">$PCI_DEV</span> <span class="nv">$LPC_DEV</span> <span class="nv">$NET</span> <span class="nv">$IMG_CD</span> <span class="nv">$IMG_HDD</span> <span class="nv">$UUID</span> <span class="nt">-f</span> kexec,<span class="nv">$KERNEL</span>,<span class="nv">$INITRD</span>,<span class="s2">"</span><span class="nv">$CMDLINE</span><span class="s2">"</span>
</code></pre></div></div>
<p>The <code class="language-plaintext highlighter-rouge">CMDLINE</code> is taken from the boot2docker <a href="https://github.com/boot2docker/boot2docker/blob/f996284ecf003356e6d749394e95804dc62708e8/rootfs/isolinux/isolinux.cfg#L7Kernel">isolinux configuration</a>.</p>
<h2 id="start-the-xhyve-boot2docker-vm">Start the xhyve boot2docker VM</h2>
<p>To be able to access networking xhyve has to be run as root, so start it with <code class="language-plaintext highlighter-rouge">sudo ./xhyve-boot2docker.sh</code>.<br />
Supposedly it also works if you code sign the <code class="language-plaintext highlighter-rouge">xhyve</code> binary but I haven’t tried that.</p>
<p>This will take a bit of time and then give the password prompt for the <code class="language-plaintext highlighter-rouge">docker</code> user. Log in using the password <code class="language-plaintext highlighter-rouge">tcuser</code> and that’s it, boot2docker is running inside xhyve! :)</p>
<p>Note: to shutdown the xhyve boot2docker VM issue <code class="language-plaintext highlighter-rouge">sudo halt</code> from within the VM.</p>
<h2 id="create-a-persistant-disk">Create a persistant disk</h2>
<p>Obviously the previous setup isn’t perfect. boot2docker is fully running in memory with no persistant storage and only the 2GB of in-memory storage available to it. To remedy this the first thing to do is a persistant disk just like boot2docker does with Virtualbox.</p>
<p>Start by creating a virtual hard disk image. The <code class="language-plaintext highlighter-rouge">count</code> number is the size in GB the image will be.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gp">$</span><span class="w"> </span><span class="nb">dd </span><span class="k">if</span><span class="o">=</span>/dev/zero <span class="nv">of</span><span class="o">=</span>boot2docker/hdd.img <span class="nv">bs</span><span class="o">=</span>1g <span class="nv">count</span><span class="o">=</span>20
</code></pre></div></div>
<p>boot2docker in Virtualbox automatically creates an ext4 partition and labels it with <code class="language-plaintext highlighter-rouge">boot2docker-data</code>. Then during boot boot2docker checks if a partition exists with this label and uses it as its persistant partition.</p>
<p>Since none of this works automatically with xhyve some manual steps are necessary. First change the <code class="language-plaintext highlighter-rouge">xhyve-boot2docker.sh</code> script to add the <code class="language-plaintext highlighter-rouge">boot2docker.hdd.img</code> image as a harddisk:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">#!/bin/sh</span>
<span class="nv">KERNEL</span><span class="o">=</span><span class="s2">"boot2docker/vmlinuz64"</span>
<span class="nv">INITRD</span><span class="o">=</span><span class="s2">"boot2docker/initrd.img"</span>
<span class="nv">CMDLINE</span><span class="o">=</span><span class="s2">"loglevel=3 user=docker console=ttyS0 console=tty0 noembed nomodeset norestore waitusb=10:LABEL=boot2docker-data base"</span>
<span class="nv">MEM</span><span class="o">=</span><span class="s2">"-m 2G"</span>
<span class="nv">SMP</span><span class="o">=</span><span class="s2">"-c 8"</span>
<span class="nv">NET</span><span class="o">=</span><span class="s2">"-s 2:0,virtio-net,en0"</span>
<span class="nv">IMG_CD</span><span class="o">=</span><span class="s2">"-s 3,ahci-cd,boot2docker/boot2docker.iso"</span>
<span class="nv">IMG_HDD</span><span class="o">=</span><span class="s2">"-s 4,virtio-blk,boot2docker/hdd.img"</span>
<span class="nv">PCI_DEV</span><span class="o">=</span><span class="s2">"-s 0:0,hostbridge -s 31,lpc"</span>
<span class="nv">LPC_DEV</span><span class="o">=</span><span class="s2">"-l com1,stdio"</span>
<span class="c">#UUID="-U deadbeef-dead-dead-dead-deaddeafbeef"</span>
build/xhyve <span class="nv">$MEM</span> <span class="nv">$SMP</span> <span class="nv">$PCI_DEV</span> <span class="nv">$LPC_DEV</span> <span class="nv">$NET</span> <span class="nv">$IMG_CD</span> <span class="nv">$IMG_HDD</span> <span class="nv">$UUID</span> <span class="nt">-f</span> kexec,<span class="nv">$KERNEL</span>,<span class="nv">$INITRD</span>,<span class="s2">"</span><span class="nv">$CMDLINE</span><span class="s2">"</span>
</code></pre></div></div>
<p>Now start boot2docker again to partition the disk, format it and add the label.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gp">$</span><span class="w"> </span><span class="nb">sudo</span> ./xhyve-boot2docker.sh
<span class="gp">#</span><span class="w"> </span>boot messages
<span class="gp">#</span><span class="w"> </span>log <span class="k">in </span>using tcuser password again
<span class="go">
</span><span class="gp">$</span><span class="w"> </span><span class="nb">sudo </span>fdisk /dev/vda
<span class="gp">#</span><span class="w"> </span>fdisk sequence of keys to press follows
<span class="gp">p #</span><span class="w"> </span>Primary partition
<span class="gp">1 #</span><span class="w"> </span>Partition number 1
<span class="gp"><enter></span><span class="w"> </span><span class="c"># Use default value for First cylinder (1)</span>
<span class="gp"><enter></span><span class="w"> </span><span class="c"># Use default value for Last cylinder (end of disk)</span>
<span class="gp">p #</span><span class="w"> </span>print partition table to check
<span class="gp">w #</span><span class="w"> </span>Write changes to disk
<span class="go">
</span><span class="gp">#</span><span class="w"> </span>Now format and label the new partition
<span class="gp">$</span><span class="w"> </span><span class="nb">sudo </span>mkfs.ext4 /dev/vda1 <span class="nt">-L</span> boot2docker-data
<span class="gp">#</span><span class="w"> </span>Now restart to have boot2docker use the new device
<span class="gp">$</span><span class="w"> </span><span class="nb">sudo </span>halt
<span class="gp">$</span><span class="w"> </span><span class="nb">sudo</span> ./xhyve-boot2docker.sh
</code></pre></div></div>
<h2 id="access-the-docker-daemon-inside-xhyve-from-your-host">Access the docker daemon inside xhyve from your host</h2>
<p>Since currently there is no way to copy the necessary certificates between the virtual machine and the host a dirty workaround is to <a href="https://github.com/boot2docker/boot2docker/blob/master/README.md#tls-support">disable TLS</a>, which is obviously bad from a security perspective.</p>
<p>To do so edit <code class="language-plaintext highlighter-rouge">/var/lib/boot2docker/profile</code> add the line <code class="language-plaintext highlighter-rouge">DOCKER_TLS=no</code> to it and restart docker <code class="language-plaintext highlighter-rouge">sudo /etc/init.d/docker restart</code> or restart the virtual machine. Once restarted find out the IP of the virtual machine using <code class="language-plaintext highlighter-rouge">ifconfig</code> and on a terminal on your host set the <code class="language-plaintext highlighter-rouge">DOCKER_HOST</code> environment variable to this IP address. For example <code class="language-plaintext highlighter-rouge">export DOCKER_HOST=tcp://192.168.64.1:2375</code>. No you can simply use <code class="language-plaintext highlighter-rouge">docker</code> from your host to control the Docker daemon inside the virtual machine.</p>
<h2 id="benchmarks">Benchmarks</h2>
<p>xhyve looks like a very good fit for an always running virtual machine. Because of this it could maybe replace Virtualbox as the virtual machine used for boot2docker, so I ran some very basic benchmarks to check xhyve’s performance.</p>
<p>To do so I used Casey Bisson’s <a href="https://registry.hub.docker.com/u/misterbisson/simple-container-benchmarks/">simple container benchmarks</a> Docker image he used in his <a href="https://www.joyent.com/blog/docker-bake-off-aws-vs-joyent">AWS vs Joyent</a> comparison.</p>
<p>Here are the averaged results:</p>
<ul>
<li>Virtualbox
<ul>
<li>Disk: 650 MB/s</li>
<li>CPU: 22.2 MB/s</li>
</ul>
</li>
<li>xhyve
<ul>
<li>Disk: 410 MB/s</li>
<li>CPU: 6.1 MB/s</li>
</ul>
</li>
</ul>
<p>So basically right now xhyve is quiet a bit slower for both. Not really a surprise given that it’s barely over a week old ;)</p>Simon van der VeldtWarning: This is all fairly new stuff, my machine locked up if I had run a Virtualbox machine prior to starting an xhyve machine. Don’t say I didn’t warn you ;) Xhyve is a new hypervisor in the vein of KVM on Linux and bhyve on BSD. It’s actually a port of BSD’s bhyve to OS X. It’s more similar to KVM than to Virtualbox in that it’s minimal and commandline only which makes it a good fit for an always running virtual machine like boot2docker on OS X. This post documents the steps to get boot2docker running within xhyve and contains some quick benchmarks as well to compare xhyve’s performance with Virtualbox.GitHub Pages, now with GitHub Flavored Markdown, footnotes and syntax highlighting2015-04-13T00:00:00+00:002015-04-13T00:00:00+00:00http://simonvanderveldt.nl/github-pages-now-with-github-flavored-markdown-footnotes-and-syntax-highlighting<p class="alert alert-info"><strong>Update:</strong> As of the first of February 2016 GitHub Pages handles GFM, footnotes and syntax highlighting out of the box, no configuration required.<br />
See this <a href="/github-pages-with-github-flavored-markdown-footnotes-and-syntax-highlighting-simplified">new post</a> for more details.</p>
<p>In contrast to what I wrote <a href="/jekyll-github-flavored-markdown-and-footnotes">1,5 years ago</a> it’s now possible to use all of <a href="https://help.github.com/articles/github-flavored-markdown/">GitHub Flavored Markdown’s</a> features combined with footnotes and syntax highlighting on your Jekyll site whilst still having GitHub Pages build your site for you.<br />
Building your site locally and then pushing the resulting HTML is a thing of the past! :)</p>
<!--more-->
<h2 id="intro">Intro</h2>
<p>As of Redcarpet version <a href="https://github.com/vmg/redcarpet/blob/master/CHANGELOG.md#version-310">3.1.0</a> Markdown footnotes support was added. Since both <a href="https://github.com/jekyll/jekyll/blob/master/History.markdown#200--2014-05-06">Jekyll 2.0.0</a> updated its Redcarpet dependency to this version and GitHub Pages’s version of Jekyll has been <a href="https://github.com/blog/1867-github-pages-now-runs-jekyll-2-2-0">updated to version 2.2.0</a> as of <a href="https://github.com/github/pages-gem/pull/75#event-147277642">30.06.2014</a> as well this finally allows us to enable all GitHub Flavored Markdown features using Redcarpet’s extension as well as having syntax highlighting when using GitHub Pages to build our website! :)</p>
<h2 id="setup">Setup</h2>
<p>The basic setup consist of the <a href="https://github.com/vmg/redcarpet">Redcarpet</a> Markdown parser with several extensions enabled combined with <a href="http://pygments.org">Pygments</a> for syntax highlighting.</p>
<h3 id="github-flavored-markdown-with-redcarpet">GitHub Flavored Markdown with Redcarpet</h3>
<p>We start with the same settings as in the <a href="/jekyll-github-flavored-markdown-and-footnotes">old Redcarpet setup</a> and simply add <code class="language-plaintext highlighter-rouge">footnotes</code> to the list of extensions we want to enable in <code class="language-plaintext highlighter-rouge">_config.yml</code>.</p>
<p>Also, <code class="language-plaintext highlighter-rouge">fenced_code_blocks</code> can be removed as this is already being set by <a href="https://github.com/jekyll/jekyll/blob/c576d239089ed301d0c003b8afd394271cca912c/lib/jekyll/converters/markdown/redcarpet_parser.rb#L95">Jekyll</a>.</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">redcarpet</span><span class="pi">:</span>
<span class="na">extensions</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">footnotes</span>
<span class="pi">-</span> <span class="s">hard_wrap</span>
<span class="pi">-</span> <span class="s">no_intra_emphasis</span>
<span class="pi">-</span> <span class="s">autolink</span>
<span class="pi">-</span> <span class="s">strikethrough</span>
</code></pre></div></div>
<p>Et voilà, footnotes<sup id="fnref:1" role="doc-noteref"><a href="#fn:1" class="footnote" rel="footnote">1</a></sup>!</p>
<p>Note: If you want to enable some nice “smart” typographic punctuation enhancements you can add the <code class="language-plaintext highlighter-rouge">smart</code> extension, which enables <a href="http://daringfireball.net/projects/smartypants/">SmartyPants</a>.</p>
<h3 id="syntax-highlighting-with-pygments">Syntax highlighting with Pygments</h3>
<p>The <a href="/jekyll-github-flavored-markdown-and-footnotes">old Kramdown setup</a> didn’t support syntax highlighting on GitHub Pages because Kramdown doesn’t support Pygments, the only syntax highlighter currently available on GitHub Pages. It only supports the <a href="http://kramdown.gettalong.org/syntax_highlighter/coderay.html">Coderay</a> and <a href="http://kramdown.gettalong.org/syntax_highlighter/rouge.html">Rouge</a> syntax highlighters and these are unavailable when building on <a href="https://pages.github.com/versions/">GitHub Pages</a>.</p>
<p>To use Pygments we only have to set the <code class="language-plaintext highlighter-rouge">highlighter</code> option in <code class="language-plaintext highlighter-rouge">_config.yml</code> to <code class="language-plaintext highlighter-rouge">pygments</code>:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">highlighter</span><span class="pi">:</span> <span class="s">pygments</span>
</code></pre></div></div>
<p>Jekyll actually already defaults to Pygments at the moment of writing this post so doing this isn’t really necessary :)</p>
<p>Combined with Redcarpet’s fenced code blocks extension this gives us syntax highlighting that works for both the <code class="language-plaintext highlighter-rouge">highlight</code> liquid tag as well as within fenced code blocks.</p>
<div class="footnotes" role="doc-endnotes">
<ol>
<li id="fn:1" role="doc-endnote">
<p>This is a footnote! <a href="#fnref:1" class="reversefootnote" role="doc-backlink">↩</a></p>
</li>
</ol>
</div>Simon van der VeldtUpdate: As of the first of February 2016 GitHub Pages handles GFM, footnotes and syntax highlighting out of the box, no configuration required. See this new post for more details. In contrast to what I wrote 1,5 years ago it’s now possible to use all of GitHub Flavored Markdown’s features combined with footnotes and syntax highlighting on your Jekyll site whilst still having GitHub Pages build your site for you. Building your site locally and then pushing the resulting HTML is a thing of the past! :)Configuring Nikola2013-11-25T00:00:00+00:002013-11-25T00:00:00+00:00http://simonvanderveldt.nl/configuring-nikola<p>After I decided to switch this blog over from <a href="http://jekyllrb.com">Jekyll</a> to <a href="http://getnikola.com">Nikola</a> the first thing to do was to configure Nikola to my liking.<br />
Nikola offers plenty of options to configure, as of this writing it has more than 100 settings for all of its options! Since I want something as lean as possible some tweaking and workarounds were necessary to make it work the way I wanted to. This post will cover the way I configured Nikola.</p>
<p>All of Nikola’s settings are located in the file <code class="language-plaintext highlighter-rouge">conf.py</code> that is created when a new Nikola project is initilized using <code class="language-plaintext highlighter-rouge">nikola init projectname</code>.</p>
<h1 id="rename-stories-to-pages">Rename stories to pages</h1>
<p>First of all for some reason pages in Nikola are called stories :? I just want them to be called what they are - pages ;)<br />
It’s a simple as changing the PAGES tuple to:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">PAGES</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">"pages/*.md"</span><span class="p">,</span> <span class="s">"pages"</span><span class="p">,</span> <span class="s">"story.tmpl"</span><span class="p">),</span>
<span class="p">)</span>
</code></pre></div></div>
<h1 id="output-posts-and-pages-to-root-of-site">Output posts and pages to root of site</h1>
<p>Instead of outputting all posts to simonvanderveldt.nl/posts and all pages to simonvanderveldt.nl/pages I want posts and pages to reside directly under the root of my site.<br />
Both the POSTS and PAGES tuples contain 3 values per entry: the wildcard to match the source file with (<code class="language-plaintext highlighter-rouge">pages/*.md</code>), the destination (<code class="language-plaintext highlighter-rouge">pages</code>) and the template to use to render the output (<code class="language-plaintext highlighter-rouge">story.tmpl</code>).<br />
Simply change the destination to an empty string to have the output go to the root of the site.</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">POSTS</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">"posts/*.md"</span><span class="p">,</span> <span class="s">""</span><span class="p">,</span> <span class="s">"post.tmpl"</span><span class="p">),</span>
<span class="p">)</span>
<span class="n">PAGES</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">"pages/*.md"</span><span class="p">,</span> <span class="s">""</span><span class="p">,</span> <span class="s">"story.tmpl"</span><span class="p">),</span>
<span class="p">)</span>
</code></pre></div></div>
<h1 id="make-markdown-the-default-compiler">Make markdown the default compiler</h1>
<p>First of all to use markdown in any Python program the <a href="https://pypi.python.org/pypi/Markdown">Python markdown package</a> needs to be installed. This can be done with:</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">pip install markdown
</span></code></pre></div></div>
<p>To enable the processing of markdown files by Nikola add a pattern that matches your chosen markdown extension (I use *.md) to the top of the POSTS and PAGES tuples:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">POSTS</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">"posts/*.md"</span><span class="p">,</span> <span class="s">"posts"</span><span class="p">,</span> <span class="s">"post.tmpl"</span><span class="p">),</span>
<span class="p">(</span><span class="s">"posts/other format"</span><span class="p">,</span> <span class="s">"posts"</span><span class="p">,</span> <span class="s">"post.tmpl"</span><span class="p">),</span>
<span class="n">etc</span>
<span class="p">)</span>
<span class="n">PAGES</span> <span class="o">=</span> <span class="p">(</span>
<span class="p">(</span><span class="s">"pages/*.md"</span><span class="p">,</span> <span class="s">"pages"</span><span class="p">,</span> <span class="s">"story.tmpl"</span><span class="p">),</span>
<span class="p">(</span><span class="s">"pages/other format"</span><span class="p">,</span> <span class="s">"pages"</span><span class="p">,</span> <span class="s">"post.tmpl"</span><span class="p">),</span>
<span class="n">etc</span>
<span class="p">)</span>
</code></pre></div></div>
<p>It is not necessary to change anything else, Nikola has already preconfigured the actual markdown compiler for the *.md, *.mdown and *.markdown extensions (in the <code class="language-plaintext highlighter-rouge">COMPILERS</code> tuple) so after this simple change it can process existing *.md files in the <code class="language-plaintext highlighter-rouge">posts</code> and <code class="language-plaintext highlighter-rouge">pages</code> folders of a nikola project.</p>
<p>Using <code class="language-plaintext highlighter-rouge">nikola new_post</code> will create the post as *.md file as long as markdown is the first option in the POSTS and PAGES tuples.</p>
<h1 id="enable-github-flavored-markdown">Enable GitHub Flavored Markdown</h1>
<p>By default python-markdown uses the rules from <a href="http://daringfireball.net/projects/markdown/">standard markdown</a>, but I prefer the simplicity of <a href="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown (GFM)</a>.<br />
Luckily python-markdown comes with a lot of <a href="https://web.archive.org/web/20181122141519/https://python-markdown.github.io/extensions/">extensions</a> that can be easily enabled. To make python-markdown mimic GFM the following extensions have to be enabled:</p>
<ul>
<li><a href="https://web.archive.org/web/20170917091951/http://pythonhosted.org/Markdown/extensions/nl2br.html">nl2br</a>: newline to linebreak</li>
<li><a href="https://web.archive.org/web/20130328133516/http://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html">fenced_code</a>: fenced code blocks</li>
<li><a href="https://web.archive.org/web/20130328133343/http://pythonhosted.org/Markdown/extensions/smart_strong.html">smart_strong</a>: do not boldify multiple underscores in words</li>
<li><a href="https://web.archive.org/web/20130403084416/http://pythonhosted.org/Markdown/extensions/code_hilite.html">codehilite</a>: syntax highlighting (using <a href="http://pygments.org">Pygments</a>)</li>
</ul>
<p>Note that some funcionality is missing, but can be provided using third party extensions:</p>
<ul>
<li>URL autolinking: <a href="https://github.com/r0wb0t/markdown-urlize">markdown-urlize</a> is available for this but has several issues and is currently not maintained</li>
<li>Task lists: <a href="https://github.com/FND/markdown-checklist">markdown-checklist</a> is available and seems to work fine (though I’m not using this myself so no guarantees ;))</li>
<li>Strikethrough using <code class="language-plaintext highlighter-rouge">~~text~~</code>: <a href="https://github.com/aleray/mdx_del_ins">mdx_del_ins</a> provides this as well as highlighting <code class="language-plaintext highlighter-rouge">++word++</code> as inserted. Note that this can cause <a href="https://bitbucket.org/site/master/issue/8557/">issues with text about C++</a>…</li>
</ul>
<p>Enabling the extension can be done by adding them to the <code class="language-plaintext highlighter-rouge">MARKDOWN_EXTENSIONS</code> variable in Nikola’s <code class="language-plaintext highlighter-rouge">conf.py</code>:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">MARKDOWN_EXTENSIONS</span> <span class="o">=</span> <span class="p">[</span><span class="s">"nl2br"</span><span class="p">,</span> <span class="s">"fenced_code"</span><span class="p">,</span>
<span class="s">"smart_strong"</span><span class="p">,</span><span class="s">"codehilite(linenums=table)"</span><span class="p">]</span>
</code></pre></div></div>
<p>Codehilite’s <code class="language-plaintext highlighter-rouge">linenums=table</code> argument uses Pygments to add linenumbers in a separate table column to the highlighted code block.</p>
<h1 id="enable-footnotes-in-markdown">Enable footnotes in markdown</h1>
<p>Footnots in markdown can be used by enabling the <a href="https://web.archive.org/web/20130328133527/http://pythonhosted.org/Markdown/extensions/footnotes.html">footnotes extension</a>.</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">MARKDOWN_EXTENSIONS</span> <span class="o">=</span> <span class="p">[</span><span class="s">"footnotes"</span><span class="p">]</span>
</code></pre></div></div>
<h1 id="enable-pretty-permalinks">Enable pretty permalinks</h1>
<p>Simple set two options to true to remove the trailing index.html from links to pages.</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">PRETTY_URLS</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">STRIP_INDEXES</span> <span class="o">=</span> <span class="bp">True</span>
</code></pre></div></div>
<h1 id="disable-comments">Disable comments</h1>
<p>Untill I’ve figured out what I want to use for comments on this site (I’m looking into using GitHub issues for this, If at all possible I don’t want to use a 3rd party hosted solution) I want to disable them.</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">COMMENT_SYSTEM</span> <span class="o">=</span> <span class="s">""</span>
</code></pre></div></div>
<h1 id="disable-some-unnecessary-parts-from-being-created">Disable some unnecessary parts from being created</h1>
<p>There are several items included in Nikola for which I have no use, for example the archive pages and the galleries. Luckily Nikola uses a very flexible system of tasks that are run in a certain order to create all parts that make up the complete website. This tasks system uses <a href="http://pydoit.org">doit</a> for the heavy lifting.</p>
<p>Run <code class="language-plaintext highlighter-rouge">nikola list</code> to get a list of all the different tasks for the current Nikola project. Almost all of the items I don’t need are separate tasks which can easily be disabled by adding them to the DISABLED_PLUGINS tuple:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">DISABLED_PLUGINS</span> <span class="o">=</span> <span class="p">[</span><span class="s">"render_galleries"</span><span class="p">,</span> <span class="s">"render_archive"</span><span class="p">]</span>
</code></pre></div></div>
<p>Note that it’s also possible to disable plugins through the command line <code class="language-plaintext highlighter-rouge">nikola ignore render_archive</code>. The disadvantage of this is that this isn’t stored in your <code class="language-plaintext highlighter-rouge">conf.py</code>. Furthermore I haven’t been able to find a way to re-add an ignored plugin :D.</p>
<h1 id="disable-source-links">Disable source links</h1>
<p>Since the source of my site is already available on GitHub I don’t want to copy them and link to the source files directly.</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">HIDE_SOURCELINK</span> <span class="o">=</span> <span class="bp">True</span>
<span class="n">COPY_SOURCES</span> <span class="o">=</span> <span class="bp">False</span>
</code></pre></div></div>
<h1 id="show-only-excerpt-on-home-page">Show only excerpt on home page</h1>
<p>Excerpts are called teasers in Nikola. By default complete posts are shown on the home page. Setting <code class="language-plaintext highlighter-rouge">INDEX_TEASERS = True</code> changes this so only the contents of posts until the TEASER_END comment are shown. Simply add <code class="language-plaintext highlighter-rouge"><!-- TEASER_END --></code> to your post where you want the excerpt to stop.</p>
<h1 id="remove-read-more-links">Remove “Read more…” links</h1>
<p>When enabling teasers a “Read more…” text is automagically added to the excerpt by Nikola. This is something I didn’t want. To disabled it simply replace the <code class="language-plaintext highlighter-rouge">READ_MORE_LINK</code> variable with an empty string</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">READ_MORE_LINK</span> <span class="o">=</span> <span class="s">""</span>
</code></pre></div></div>
<h1 id="disable-social-buttons">Disable social buttons</h1>
<p>By default some form of a social button widget is enabled. This actually isn’t part of the templates but of the conf.py (which is bad design imho). Luckily it’s easy to disable, just set SOCIAL_BUTTONS_CODE to an empty string</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">SOCIAL_BUTTONS_CODE</span> <span class="o">=</span> <span class="s">""</span>
</code></pre></div></div>
<p>Note that this will still add a bullet to the sidebar list because there is no conditional to check for an empty SOCIAL_BUTTONS_CODE variable in the default template.</p>
<h1 id="footnote-styling">Footnote styling</h1>
<p>Unfortunately using the python markdown footnotes extension adds a <code class="language-plaintext highlighter-rouge"><hr></code> element as the first element to the footnote’s <code class="language-plaintext highlighter-rouge"><div></code>. I wanted to get rid of this <code class="language-plaintext highlighter-rouge"><hr></code> element, but there is no way to change it, so I used <code class="language-plaintext highlighter-rouge">str.replace</code> to fix this in the post template <code class="language-plaintext highlighter-rouge">post.tmpl</code>:</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>${post.text().replace('<div class="footnote">\n<hr>',
'<div class="footnote">')}
</code></pre></div></div>
<p>Note that I search for both the <code class="language-plaintext highlighter-rouge">div</code> and the <code class="language-plaintext highlighter-rouge">hr</code> to prevent this code from accidentally removing <code class="language-plaintext highlighter-rouge"><hr></code> elements that are deliberately placed on the page.</p>Simon van der VeldtAfter I decided to switch this blog over from Jekyll to Nikola the first thing to do was to configure Nikola to my liking. Nikola offers plenty of options to configure, as of this writing it has more than 100 settings for all of its options! Since I want something as lean as possible some tweaking and workarounds were necessary to make it work the way I wanted to. This post will cover the way I configured Nikola.Sourcing Python files in the interactive interpreter2013-11-04T00:00:00+00:002013-11-04T00:00:00+00:00http://simonvanderveldt.nl/sourcing-python-files-in-the-interactive-interpreter<p>One of the most useful features of a Linux shell I often use is sourcing of files. Sourcing a file basically means that the file’s code is run as if you typed it in yourself. Everything the code in the file does is applied to the shell you’re currently using and all its global variables are added to your current shell. It’s also possible to do this in Python, with the function <a href="http://docs.python.org/2/library/functions.html#execfile"><code class="language-plaintext highlighter-rouge">execfile</code></a>.</p>
<p>All you have to do is run <code class="language-plaintext highlighter-rouge">execfile</code> with the path to the file you want to source as the only argument:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">execfile</span><span class="p">(</span><span class="s">'filename.py'</span><span class="p">)</span>
</code></pre></div></div>
<p>All the code inside the file you source will be run by the interpreter and all its global variables as well as its functions and classes will we added to your interactive interpreter’s session.</p>
<p>If the file you want to source is in a different directory either enter the full path to the file in the execfile command or change to the directory where the file is located. In the default Python interactive interpreter you can change the directory by doing:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">os</span>
<span class="n">os</span><span class="p">.</span><span class="n">chdir</span><span class="p">(</span><span class="s">'/path/to/directory'</span><span class="p">)</span>
</code></pre></div></div>
<p>Note that this path notation also works on Windows (no need to type <code class="language-plaintext highlighter-rouge">C:\path\etc</code>).</p>
<p>If you use IPython you don’t need to import anything since it has <a href="http://ipython.org/ipython-doc/rel-1.1.0/interactive/shell.html#directory-management">filesystem navigation</a> built in (using <a href="http://ipython.org/ipython-doc/dev/interactive/tutorial.html#magic-functions">magic functions</a>), so you can just use:</p>
<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">cd</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">directory</span>
</code></pre></div></div>Simon van der VeldtOne of the most useful features of a Linux shell I often use is sourcing of files. Sourcing a file basically means that the file’s code is run as if you typed it in yourself. Everything the code in the file does is applied to the shell you’re currently using and all its global variables are added to your current shell. It’s also possible to do this in Python, with the function execfile.LXC on Debian Wheezy2013-10-21T00:00:00+00:002013-10-21T00:00:00+00:00http://simonvanderveldt.nl/lxc-on-debian-wheezy<p><a href="http://linuxcontainers.org">LXC (LinuX Containers)</a> offers a lot of the advantages of (para)virtualisation with the added benefits that it can run on any kind of hardware (it doesn’t need hardware support for virtualisation) with lower overhead than virtualisation.<br />
The virtual environments that LXC provides are comparable to a chroot but LXC adds control over the virtual environments resources like CPU-time and network-usage and offers more isolation.<br />
This also means it’s only possible to run the same “family” of guest operating systems as the host. I.e. it’s not possible to run Windows using LXC, but it is possible to run different Linux distributions like a Debian and Fedora guest on an Arch Linux host.<br />
Note that if you need a really secure environment LXC isn’t the right choice, stick with paravirtualisation like <a href="http://www.linux-kvm.org">KVM</a> or <a href="http://www.xenproject.org">XEN</a> instead.</p>
<h1 id="installing-lxc">Installing LXC</h1>
<p>The LXC tools are included in the main Debian package repository, so installing it is very simple:</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo apt-get install lxc
</span></code></pre></div></div>
<h1 id="creating-a-new-container">Creating a new container</h1>
<p>Creating a new container can we done with the <code class="language-plaintext highlighter-rouge">lxc-create</code> command</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo lxc-create -n containername -t templatename
</span></code></pre></div></div>
<p>You will see some feedback about the container creation on your screen including the (root) username and password you can use to login to the container once you start it.</p>
<h2 id="lxc-templates">LXC Templates</h2>
<p>LXC template are shell scripts that automate the creation of a certain type of container. The templates can be found in <code class="language-plaintext highlighter-rouge">/usr/share/lxc/templates/</code>, these are the available templates in Debian Wheezy:</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">ls -hl /usr/share/lxc/templates/
</span><span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 12K Aug 22 2012 lxc-altlinux
<span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 14K Aug 22 2012 lxc-archlinux
<span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 24K Aug 22 2012 lxc-debconf
<span class="gp">></span><span class="w"> </span>drwxr-xr-x 2 0 4.0K May 21 2013 lxc-debconf.d
<span class="gp">></span><span class="w"> </span>lrwxrwxrwx 1 0 11 Aug 22 2012 lxc-debian -> lxc-debconf
<span class="gp">></span><span class="w"> </span>lrwxrwxrwx 1 0 13 Aug 22 2012 lxc-debian.d -> lxc-debconf.d
<span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 9.8K Aug 22 2012 lxc-fedora
<span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 9.9K Aug 22 2012 lxc-opensuse
<span class="gp">></span><span class="w"> </span>lrwxrwxrwx 1 0 11 Aug 22 2012 lxc-progress -> lxc-debconf
<span class="gp">></span><span class="w"> </span>lrwxrwxrwx 1 0 13 Aug 22 2012 lxc-progress.d -> lxc-debconf.d
<span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 4.0K Aug 22 2012 lxc-sshd
<span class="gp">></span><span class="w"> </span><span class="nt">-rwxr-xr-x</span> 1 0 7.6K Aug 22 2012 lxc-ubuntu-cloud
</code></pre></div></div>
<p>To use a template simply remove <code class="language-plaintext highlighter-rouge">lxc-</code> from the template’s name. So to use the <code class="language-plaintext highlighter-rouge">lxc-debian</code> you only have to write <code class="language-plaintext highlighter-rouge">debian</code> as templatename.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo lxc-create -n containername -t debian
</span></code></pre></div></div>
<h1 id="overview-and-status-of-containers">Overview and status of containers</h1>
<p>To see if the container was created succesfully we use the <code class="language-plaintext highlighter-rouge">lxc-list</code> command. This will show all available LXC containers grouped by their status (running, frozen and stopped). Our newly created container should be listed in the stopped section.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo lxc-list
</span><span class="gp">></span>RUNNING
<span class="gp">></span><span class="w">
</span><span class="gp">></span>FROZEN
<span class="gp">></span><span class="w">
</span><span class="gp">></span>STOPPED
<span class="gp">></span><span class="w"> </span>containername
</code></pre></div></div>
<h1 id="starting-a-container">Starting a container</h1>
<p>Starting a container can be done with the <code class="language-plaintext highlighter-rouge">lxc-start</code> command. Note that you want to add the <code class="language-plaintext highlighter-rouge">-d</code> switch to make the container daemonize, if you don’t do that it will take over your current terminal session and you won’t be able to exit back to it.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo lxc-start -d -n containername
</span></code></pre></div></div>
<p>Now if we run <code class="language-plaintext highlighter-rouge">lxc-list</code> our container is show as running</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo lxc-list
</span><span class="gp">></span>RUNNING
<span class="gp">></span><span class="w"> </span>containername
<span class="gp">></span><span class="w">
</span><span class="gp">></span>FROZEN
<span class="gp">></span><span class="w">
</span><span class="gp">></span>STOPPED
</code></pre></div></div>
<h1 id="using-a-container">Using a container</h1>
<p>To actually use a container from your host we make use of the ‘lxc-console’ command.</p>
<div class="language-console highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="go">sudo lxc-console -n containername
</span></code></pre></div></div>
<p>After doing this you will see a new terminal with a login prompt just as if you just started up a new session. You can login with the username and password that were given to you when you created the container.</p>
<p>That’s it, you are now inside your Debian container and you can use it just like a normal install of Debian :)</p>Simon van der VeldtLXC (LinuX Containers) offers a lot of the advantages of (para)virtualisation with the added benefits that it can run on any kind of hardware (it doesn’t need hardware support for virtualisation) with lower overhead than virtualisation. The virtual environments that LXC provides are comparable to a chroot but LXC adds control over the virtual environments resources like CPU-time and network-usage and offers more isolation. This also means it’s only possible to run the same “family” of guest operating systems as the host. I.e. it’s not possible to run Windows using LXC, but it is possible to run different Linux distributions like a Debian and Fedora guest on an Arch Linux host. Note that if you need a really secure environment LXC isn’t the right choice, stick with paravirtualisation like KVM or XEN instead.HTML heading styling inside a section vs inside a div2013-09-30T00:00:00+00:002013-09-30T00:00:00+00:00http://simonvanderveldt.nl/html-heading-styling-inside-a-section-vs-inside-a-div<p>Just quick heads-up in case someone is wondering why his or hers <code class="language-plaintext highlighter-rouge"><h1></code> isn’t looking like they expect.<br />
Modern browsers apply different styling for <code class="language-plaintext highlighter-rouge"><h1></code> elements inside a <code class="language-plaintext highlighter-rouge"><div></code> vs inside one of the <a href="http://caniuse.com/#feat=html5semantic">new semantic elements</a> like <code class="language-plaintext highlighter-rouge"><article></code>, <code class="language-plaintext highlighter-rouge"><aside></code>, <code class="language-plaintext highlighter-rouge"><nav></code> or <code class="language-plaintext highlighter-rouge"><section></code>.<br />
This is because these new semantic elements influence the <a href="http://html5doctor.com/outlines/">document outline</a> and the modern browsers try to show that to you in a graphical way.</p>
<p>Both Chrome en Firefox use a so called User Agent Stylesheet to define the default styling of alle lements. This is basically just a .css file which defines the default browser styling of all elements.<br />
See below for en extract from both Chrome and Firefox’s with the regular <code class="language-plaintext highlighter-rouge"><h1></code> tag and 1 inside an <code class="language-plaintext highlighter-rouge"><article></code> or <code class="language-plaintext highlighter-rouge"><section></code> and the regular <code class="language-plaintext highlighter-rouge"><h2></code> for comparison. Both links point to the current/tip/trunk version of the User Agent Stylesheet.</p>
<p>Chrome’s <a href="http://trac.webkit.org/browser/trunk/Source/WebCore/css/html.css#L155">html.css</a>:</p>
<div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">h1</span> <span class="p">{</span>
<span class="nl">display</span><span class="p">:</span> <span class="nb">block</span><span class="p">;</span>
<span class="nl">font-size</span><span class="p">:</span> <span class="m">2em</span><span class="p">;</span>
<span class="nl">-webkit-margin-before</span><span class="p">:</span> <span class="m">0.67</span><span class="n">__qem</span><span class="p">;</span>
<span class="nl">-webkit-margin-after</span><span class="p">:</span> <span class="m">0.67em</span><span class="p">;</span>
<span class="nl">-webkit-margin-start</span><span class="p">:</span> <span class="m">0</span><span class="p">;</span>
<span class="nl">-webkit-margin-end</span><span class="p">:</span> <span class="m">0</span><span class="p">;</span>
<span class="nl">font-weight</span><span class="p">:</span> <span class="nb">bold</span>
<span class="p">}</span>
<span class="nd">:-webkit-any</span><span class="o">(</span><span class="nt">article</span><span class="o">,</span><span class="nt">aside</span><span class="o">,</span><span class="nt">nav</span><span class="o">,</span><span class="nt">section</span><span class="o">)</span> <span class="nt">h1</span> <span class="p">{</span>
<span class="nl">font-size</span><span class="p">:</span> <span class="m">1.5em</span><span class="p">;</span>
<span class="nl">-webkit-margin-before</span><span class="p">:</span> <span class="m">0.83</span><span class="n">__qem</span><span class="p">;</span>
<span class="nl">-webkit-margin-after</span><span class="p">:</span> <span class="m">0.83em</span><span class="p">;</span>
<span class="p">}</span>
<span class="nt">h2</span> <span class="p">{</span>
<span class="nl">display</span><span class="p">:</span> <span class="nb">block</span><span class="p">;</span>
<span class="nl">font-size</span><span class="p">:</span> <span class="m">1.5em</span><span class="p">;</span>
<span class="nl">-webkit-margin-before</span><span class="p">:</span> <span class="m">0.83</span><span class="n">__qem</span><span class="p">;</span>
<span class="nl">-webkit-margin-after</span><span class="p">:</span> <span class="m">0.83em</span><span class="p">;</span>
<span class="nl">-webkit-margin-start</span><span class="p">:</span> <span class="m">0</span><span class="p">;</span>
<span class="nl">-webkit-margin-end</span><span class="p">:</span> <span class="m">0</span><span class="p">;</span>
<span class="nl">font-weight</span><span class="p">:</span> <span class="nb">bold</span>
<span class="p">}</span>
</code></pre></div></div>
<p>FireFox’s <a href="https://hg.mozilla.org/mozilla-central/file/a475f94bb1b1/layout/style/html.css#l164">html.css</a></p>
<div class="language-css highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">h1</span> <span class="p">{</span>
<span class="nl">display</span><span class="p">:</span> <span class="nb">block</span><span class="p">;</span>
<span class="nl">font-size</span><span class="p">:</span> <span class="m">2em</span><span class="p">;</span>
<span class="nl">font-weight</span><span class="p">:</span> <span class="nb">bold</span><span class="p">;</span>
<span class="nl">margin</span><span class="p">:</span> <span class="m">.67em</span> <span class="m">0</span><span class="p">;</span>
<span class="p">}</span>
<span class="nt">h2</span><span class="o">,</span>
<span class="nd">:-moz-any</span><span class="o">(</span><span class="nt">article</span><span class="o">,</span> <span class="nt">aside</span><span class="o">,</span> <span class="nt">nav</span><span class="o">,</span> <span class="nt">section</span><span class="o">)</span>
<span class="nt">h1</span> <span class="p">{</span>
<span class="nl">display</span><span class="p">:</span> <span class="nb">block</span><span class="p">;</span>
<span class="nl">font-size</span><span class="p">:</span> <span class="m">1.5em</span><span class="p">;</span>
<span class="nl">font-weight</span><span class="p">:</span> <span class="nb">bold</span><span class="p">;</span>
<span class="nl">margin</span><span class="p">:</span> <span class="m">.83em</span> <span class="m">0</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>
<p>Both of them actually apply this behaviour for up to 5 levels deep nesting of <code class="language-plaintext highlighter-rouge"><article></code>, <code class="language-plaintext highlighter-rouge"><aside></code>, <code class="language-plaintext highlighter-rouge"><nav></code> and <code class="language-plaintext highlighter-rouge"><section></code> elements.<br />
So if you have an <code class="language-plaintext highlighter-rouge"><h1></code> inside a <code class="language-plaintext highlighter-rouge"><section></code> which is inside an <code class="language-plaintext highlighter-rouge"><article></code> it will actually show up the same as a regular <code class="language-plaintext highlighter-rouge"><h3></code>.</p>
<p>Note that on these browsers this means that to get a regularly styled <code class="language-plaintext highlighter-rouge"><h1></code> element it has to be outside any of the above mentioned elements or you’ll have to define the styling yourself!</p>
<p>Also note that at the moment you <a href="http://blog.paciellogroup.com/2013/10/html5-document-outline/">shouldn’t rely</a> on <code class="language-plaintext highlighter-rouge"><section></code> to style your headings because it isn’t fully supported on all browsers.</p>Simon van der VeldtJust quick heads-up in case someone is wondering why his or hers <h1> isn’t looking like they expect. Modern browsers apply different styling for <h1> elements inside a <div> vs inside one of the new semantic elements like <article>, <aside>, <nav> or <section>. This is because these new semantic elements influence the document outline and the modern browsers try to show that to you in a graphical way.Jekyll, Github Flavored Markdown and footnotes2013-09-09T00:00:00+00:002013-09-09T00:00:00+00:00http://simonvanderveldt.nl/jekyll-github-flavored-markdown-and-footnotes<p class="alert alert-info"><strong>Update:</strong> As of Jekyll 2.0.0 it’s possible to have our GitHub Pages cake and eat it :)<br />
See this <a href="/github-pages-now-with-github-flavored-markdown-footnotes-and-syntax-highlighting">new post</a> for more details.</p>
<p><a href="http://jekyllrb.com/">Jekyll</a> uses <a href="https://github.com/vmg/redcarpet">redcarpet</a> as its default <a href="http://daringfireball.net/projects/markdown/">Markdown</a> parser for newly generated sites as of version <a href="https://github.com/mojombo/jekyll/pull/1245">v1.1.0</a>. It does so by setting <code class="language-plaintext highlighter-rouge">markdown: redcarpet</code> in <code class="language-plaintext highlighter-rouge">_config.yml</code>.<br />
Redcarpet is the markdown parser used by GitHub, but in its default config it actually doesn’t parse using the <a href="https://help.github.com/articles/github-flavored-markdown">GitHub Flavored Markdown</a> (GFM) rules.</p>
<!--more-->
<p>To change this add the following to Jekyll’s _config.yml:</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">redcarpet</span><span class="pi">:</span>
<span class="na">extensions</span><span class="pi">:</span>
<span class="pi">-</span> <span class="s">hard_wrap</span>
<span class="pi">-</span> <span class="s">no_intra_emphasis</span>
<span class="pi">-</span> <span class="s">autolink</span>
<span class="pi">-</span> <span class="s">strikethrough</span>
<span class="pi">-</span> <span class="s">fenced_code_blocks</span>
</code></pre></div></div>
<p>This is also documented on the Jekyll documentation on GitHub about GitHub pages in the chapter <a href="https://github.com/mojombo/jekyll/blob/8f932dbfa2709261af4999b4429f09bc5665b83e/docs/github-pages.md#mimicking-github-flavored-markdown">Mimicking Github Flavored Markdown</a>. Unfortunately this isn’t available in the publicly available documentation on the Jekyll <a href="http://jekyllrb.com/docs/github-pages/">website</a>.</p>
<h2 id="footnotes">Footnotes</h2>
<p>Unfortunately only the current master branch of redcarpet <a href="https://github.com/vmg/redcarpet/pull/271">supports</a> footnotes (and Jekyll doesn’t even support <a href="https://github.com/mojombo/jekyll/pull/1299">v3.0.0</a> at the moment) so with the default setup it isn’t possible to add footnotes to posts.</p>
<p>Luckily there are other MarkDown parsers to choose from. A short comparison of them can be found on <a href="http://bloerg.net/2013/03/07/using-kramdown-instead-of-maruku.html">bloerg.net</a>.</p>
<p>Just like Matthias concluded in this comparison I came to the conclusion that at the moment <a href="http://kramdown.gettalong.org/">kramdown</a> is the best option to use as my MarkDown parser. Unlike Matthias I feel no need to use Code Highlighting using <a href="http://pygments.org/">Pygments</a> because <a href="http://coderay.rubychan.de/">CodeRay</a> (don’t mind the ugly site!) works perfectly fine for me, I don’t have to modify Jekyll or Kramdown or have to use workarounds to make Jekyll parse the MarkDown files correctly and it just feel (c)leaner to me to stay with only Ruby dependencies.</p>
<h2 id="using-kramdown-inside-jekyll">Using Kramdown inside Jekyll</h2>
<p>Using Kramdown inside Jekyll is very easy, the only thing you have to do is set the <code class="language-plaintext highlighter-rouge">markdown</code> configuration option in your <code class="language-plaintext highlighter-rouge">_config.yml</code> to <code class="language-plaintext highlighter-rouge">kramdown</code> (and install the kramdown if it isn’t installed already).</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">markdown</span><span class="pi">:</span> <span class="s">kramdown</span>
</code></pre></div></div>
<p>Since I still want to make use of GFM some additional settings from kramdown have to be set just like with redcarpet. Kramdown actually already supports most of the parsing features needed for GFM, but uses tilde’s for <a href="http://kramdown.gettalong.org/syntax.html#fenced-code-blocks">fenced code blocks</a> and doesn’t add hard line-breaks inside paragraphs. This is easily fixed though by setting the kramdown <code class="language-plaintext highlighter-rouge">input</code> configuration option to <code class="language-plaintext highlighter-rouge">GFM</code> in your <code class="language-plaintext highlighter-rouge">_config.yml</code>.</p>
<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">markdown</span><span class="pi">:</span> <span class="s">kramdown</span>
<span class="na">kramdown</span><span class="pi">:</span>
<span class="na">input</span><span class="pi">:</span> <span class="s">GFM</span>
</code></pre></div></div>
<p>That’s it, now you can use GFM and footnotes<sup id="fnref:1" role="doc-noteref"><a href="#fn:1" class="footnote" rel="footnote">1</a></sup> in your Jekyll MarkDown posts!</p>
<div class="footnotes" role="doc-endnotes">
<ol>
<li id="fn:1" role="doc-endnote">
<p>Example footnote. <a href="#fnref:1" class="reversefootnote" role="doc-backlink">↩</a></p>
</li>
</ol>
</div>Simon van der VeldtUpdate: As of Jekyll 2.0.0 it’s possible to have our GitHub Pages cake and eat it :) See this new post for more details. Jekyll uses redcarpet as its default Markdown parser for newly generated sites as of version v1.1.0. It does so by setting markdown: redcarpet in _config.yml. Redcarpet is the markdown parser used by GitHub, but in its default config it actually doesn’t parse using the GitHub Flavored Markdown (GFM) rules.