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. At its simplest, each Distill post is just a single HTML file with one special script tag.
<!doctype html>
<meta charset="utf-8">
<script src="https://distill.pub/template.v1.js"></script>
<dt-article>
<h1>Hello World</h1>
</dt-article>This script tag will modify your post in your browser, adding the Distill styling and functionality. When we publish your article, we will bake in these transformations, but during development it’s handy to be able to preview it locally (It even works without a web server).
A typical Distill post will be quite a bit longer than the one above. 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="https://distill.pub/template.v1.js"></script>
<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>
<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>
<dt-appendix>
</dt-appendix>
<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},
url={https://arxiv.org/pdf/1502.04623.pdf}
}
</script>Because all the templating is delivered via a script tag, you are generally free to develop however you are most comfortable. The only requirements are that each article must be its own Github repository. The simplest setup would be a repository that contained a single HTML file, along with any additional assets, like images or javascript files. Note, in this default setup, all files in the root of the repository will be published. Note, also, in this configuration you generally will not even need to run a static local webserver. You can just open the index.html
image.jpg
index.html
script.jsIf you have a more complicated build process, or have files you don’t want published, put your output in a public
build/
_index.html
package.json
public/
index.html
image.jpgYou’ll need to describe some data about you post — title, description, authors, etc. For this use the <script type="text/front-matter">
<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>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">
<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},
url={https://arxiv.org/pdf/1502.04623.pdf},
}
</script>(We strongly encourage you to populate the url
Citations are then used in the article body with the <dt-cite>keykey
<dt-cite key="gregor2015draw"></dt-cite>The citation is presented inline like this:
Distill chose a numerical inline citation style to improve readability of citation dense articles and because many of the benefits of longer citations are obviated by dispalying more information on hover. However, we consider it good style to mention author last names if you discuss something at length and it fits into the flow well — the authors are human and it’s nice for them to have the community associate them with their work.
Just wrap the text you would like to show up in a footnote in a <dt-fn>
<dt-fn>This will become a hoverable footnote.</dt-fn>Syntax highlighting is provided within <dt-code><dt-code language="html">let x = 10;</dt-code>block
<dt-code block language="javascript">
var x = 25;
function(x){
return x * x;
}
</dt-code>Please use MathJax or KaTeX for equations.
In the future, we may provide a more structured way to handle equations so we can pre-render them on the server side.
For static diagrams, we recommend using a vector graphics tool, like Adobe Illustrator, Sketch or Inkscape. For equations in diagrams, inkscape has a plugin to support LaTeX equations, while Illustrator integrates well with tools like Equation Maker.
For dynamic diagrams we recommend D3.js. For complex diagrams where you only want to animate part of them, you can draw a static diagram, tag elements of your diagram with classes or ids, and then manipulate them with D3.
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
.l-body-outset
.l-middle-outset
.l-page-outset
Occasionally you’ll want to use the full browser width. For this, use .l-screen
.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 centereddt-article
<dt-article class="centered">
<h1>Hello World</h1>
</dt-article>You can toggle it on this article by clicking here
An appendix can be added after your article, using the <dt-appendix>
<dt-article>
...
</dt-article>
<dt-appendix>
<h3>Appendix Section Title</h3>
<p>section content<p>
</dt-appendix>You may wish to include the following sections in your appendix:
That should do it. If you have any questions or bugs to file, feel free to open an issue on GitHub.