How to Create a Distill Article

A collection of examples and best practices for creating interactive explanatory articles using the Distill web framework

Getting Started

Here is the smallest distill post.

<!doctype html> <meta charset="utf-8"> <script src="http://distill.pub/template.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="http://distill.pub/template.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>

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.

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.

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 key="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>

Footnotes

Just wrap the text you would like to show up in a footnote in a dt-fn tag. The number of the footnote will be automatically generated. This text will be shown on hover.

<dt-fn>This will become a hoverable footnote.</dt-fn>

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.

.l-body

For images you want to display a little larger, try these:

.l-middle

.l-page

All of these have an outset variant if you want to poke out from the body text a little bit. For instance:

.l-body-outset

Occasionally you’ll want to use the full browser width. For this, use .l-screen. You can also inset the element a little from the edge of the browser by using the inset variant.

.l-screen

.l-screen-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 layouts.

.l-body.side

.l-middle.side

.l-page.side

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.

.l-gutter

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.

You can also use an alternate centered layout by adding a centered class to the dt-article element.

<dt-article class="centered"> <h1>Hello World</h1> </dt-article>

You can toggle it on this article by clicking here