How to Create a Distill Article
A collection of examples and best practices for creating interactive explanatory articles using the Distill web framework
Distill ships with a CSS framework and a collection of custom web components that make building interactive academic articles easier than with raw HTML, CSS and JavaScript. This reference article details several examples and best practices for how to use both frameworks.
Getting Started
Here is the smallest distill post.
<!doctype html>
<meta charset="utf-8">
<script src="../dist/template.min.js"></script>
<dt-article>
<h1>Hello World</h1>
</dt-article>
A typical distill post will be quite a bit longer than this though. Below is a more complete example. Don’t worry if some of the tags don’t make sense, they’re all documented further in this post.
<!doctype html>
<meta charset="utf-8">
<script src="../dist/template.min.js"></script>
<script type="text/front-matter">
title: Article Title
description: Description of the post
published: Jan 10, 2017
authors:
- Chris Olah: http://colah.github.io
- Shan Carter: http://shancarter.com
affiliations:
- Google Brain: http://g.co/brain
- Google Brain: http://g.co/brain
</script>
<dt-article>
<h1>Hello World</h1>
<h2>A description of the article</h2>
<dt-byline></dt-byline>
<p>This is the first paragraph of the article.</p>
<p>We can also cite <dt-cite key="gregor2015draw"></dt-cite> external publications.</p>
</dt-article>
<script type="text/bibliography">
@article{gregor2015draw,
title={DRAW: A recurrent neural network for image generation},
author={Gregor, Karol and Danihelka, Ivo and Graves, Alex and Rezende, Danilo Jimenez and Wierstra, Daan},
journal={arXivreprint arXiv:1502.04623},
year={2015}
}
</script>
Markdown
Markdown is supported as an alternative to html for the <dt-article> element.
<!doctype html>
<meta charset="utf-8">
<script src="../dist/template.min.js"></script>
<dt-article markdown>
# Hello World
## A description of the post
First paragraph of the article.
</dt-article>
<script type="text/bibliography"></script>
We use marked as the rendering engine, with github flavored markdown and smartypants enabled. In development mode the markdown is translated in the client after the dom content has loaded, but when published, the translation is precompiled.
Front Matter
You’ll need to describe some data about you post — title, description, authors, etc. For this use the <script type="text/front-matter"> tag.
<script type="text/front-matter">
title: Article Title
description: Description of the post
authors:
- Chris Olah: http://colah.github.io
- Shan Carter: http://shancarter.com
affiliations:
- Google Brain: http://g.co/brain
- Google Brain: http://g.co/brain
</script>
Citations
Bibtex is the supported way of making academic citations. You first need have a global definition of all your possible citations. For this we’ll use the <script type="text/bibliography"> element.
<script type="text/bibliography"">
@article{gregor2015draw,
title={DRAW: A recurrent neural network for image generation},
author={Gregor, Karol and Danihelka, Ivo and Graves, Alex and Rezende, Danilo Jimenez and Wierstra, Daan},
journal={arXivreprint arXiv:1502.04623},
year={2015}
}
@article{mercier2011humans,
title={Why do humans reason? Arguments for an argumentative theory},
author={Mercier, Hugo and Sperber, Dan},
journal={Behavioral and brain sciences},
volume={34},
number={02},
pages={57--74},
year={2011},
publisher={Cambridge Univ Press}
}
</script>
Citations are then used in the article body with the <dt-cite> tag. The article attribute is a reference to the id provided in the bibiography.
<dt-cite ket="gregor2015draw"></dt-cite>
Code Blocks
Syntax highlighting is provided within <dt-code> tags. An example of inline code snippets: <dt-code language="html">let x = 10;</dt-code>. For larger blocks of code, add a block attribute:
<dt-code block language="javascript">
var x = 25;
function(x){
return x * x;
}
</dt-code>
Layouts
The main text column is referred to as the body. It is the assumed layout of any direct descendents of the dt-article
element.
Occasionally you’ll want to use the full browser width. For this, use screen. You can also inset the element a little from the edge of the browser by appending, you guessed it, inset
.
Often you want to position smaller images so as not to completely interrupt the flow of your text. Or perhaps you want to put some text in the margin as an aside or to signal that it’s optional content. For these cases we’ll use the float-based .side
layouts.
They are all floated to the right and anchored to the right-hand edge of the position you specify. By default, each will take up approximately half of the width of the standard layout position, but you can override the width with a more specific selector.
The final layout is for marginalia, asides, and footnotes. It does not interrupt the normal flow of .l-body
sized text except on mobile screen sizes.