The Distill Template:
Craft Beautiful Blogs

It's nice to have a cute interactive banner!

Welcome to the Distill Blog Template! This framework is based on the distill.pub design and has been adapted to make it easy for you to create beautiful, interactive technical blogs. Whether you're writing about machine learning, data science, physics, or any technical topic, this template provides the structure and components you need.

This template includes support for mathematics, interactive visualizations, citations, footnotes, and more. In this guide, we'll walk you through the structure of the template and how to customize it for your own blog.

The template is built with the following features in mind:

1. Beautiful typography and layout: The template follows Distill's clean, readable design principles with responsive layouts that work well on desktop and mobile.

2. Support for interactive components: You can include interactive visualizations, like the memory widget shown below:

Getting Started with the Template

Let's walk through how to use this template to create your own blog:

Installation and Setup

First, duplicate the repository and clone it to your local machine and install the dependencies:

git clone https://huggingface.co/spaces/lvwerra/distill-blog-template cd distill-blog-template npm install

To run the development server:

npm run dev

This will start a local server at http://localhost:8080 where you can preview your blog as you edit it.

Editing the Front Matter

The front matter contains metadata about your blog post, such as the title, description, and author information. Edit the <d-front-matter> section at the top of src/index.html:

<d-front-matter> <script id='distill-front-matter' type="text/json">{ "title": "Your Blog Title", "description": "A brief description of your blog", "published": "Month Day, Year", "affiliation": {"name": "Your Organization"}, "authors": [ { "author":"Your Name", "authorURL":"https://your-website.com" } ], "katex": { "delimiters": [ {"left": "$$", "right": "$$", "display": false} ] } } </script> </d-front-matter>

An the corresponding entries in src/distill.js in the bylineTemplate.

Writing Your Content

Your main content goes within the <d-article> tags. You can use standard HTML tags with some special Distill components:

Mathematical Equations

You can include inline math using <d-math>x^2 + y^2 = z^2</d-math> which renders as x^2 + y^2 = z^2.

For block equations, use <d-math block>E = mc^2</d-math>:

E = mc^2

Code

It's great to include code samples in your blog post. In-line you can do it via the <code> tags. For code blocks you can use the <d-code block language="clike"> tags. Take the for example the following block:

<d-code block language="python"> def print_hello_world(): print("hello world") </d-code>

It will render as:

def print_hello_world(): print("hello world")

Finally, if you want to include code from GitHub you can use emgithub.com and for example create a collapsable widget like this:

<details style="background: #f6f8fa; border: 1px solid #d0d7de; border-radius: 6px; margin: 1em 0;"> <summary style="padding: 12px; cursor: pointer; user-select: none; background: #f3f4f6; border-bottom: 1px solid #d0d7de;"> 👉 Naive DP implementation with overlap in Picotron (Click to expand) </summary> <div class="code-embed-container" style="margin: 0; border-radius: 0; overflow-x: scroll; width: max-content; min-width: 100%; font-size: 8px;"></div> <script src="https://emgithub.com/embed-v2.js?target=https%3A%2F%2Fgithub.com%2Fhuggingface%2Fpicotron%2Fblob%2F0035cce0e04afd6192763b11efe50010d8ad0f71%2Fpicotron%2Fdata_parallel%2Fdata_parallel.py%23L10-L60&style=github&type=code&showBorder=off&showLineNumbers=on&showFileMeta=on&showCopy=on&showFullPath=on"> </script> </div> </details>

Which will display as follows:

👉 Naive DP implementation with overlap in Picotron (Click to expand)

Asides

You can include side notes using the <aside>...</aside> tag:

Figures and Images

Include figures with captions:

<figure> <img src="/assets/images/placeholder.png" alt="A placeholder image"> <figcaption>Caption for your figure</figcaption> </figure>

This will show the following:

A placeholder image
Caption for your figure

Tables

You can easily add tables with the default HTML formatting:

<table> <thead> <tr> <th><strong>Model</strong></th> <th><strong>Accuracy</strong></th> <th><strong>Speed</strong></th> </tr> </thead> <tbody> <tr> <td>Model A</td> <td>95%</td> <td>Fast</td> </tr> <tr> <td>Model B</td> <td>98%</td> <td>Medium</td> </tr> <tr> <td>Model C</td> <td>99%</td> <td>Slow</td> </tr> </tbody> </table>

This will render as a table as expected:

Model Accuracy Speed
Model A 95% Fast
Model B 98% Medium
Model C 99% Slow

Citations

Citations can be included using <d-cite bibtex-key="example2023"></d-cite> tags and a separate bibliography file:

As shown in the paper, this approach has several advantages.

Building and Deploying

When you're ready to build your blog for production:

npm run build

This will create optimized files in the dist/ directory. You can then commit and push the changes back to the space and see the result.

Interactive Components

You can for example include interactive Plotly visualizations in your blog by creating HTML fragments:

To generate these charts, run the included Python script:

pip install numpy plotly pandas python plotly_example.py

This creates HTML fragments in the src/fragments/ directory that you can include in your blog using the id attribute matching the fragment name.

Using HTML Fragments

This template supports HTML fragments, which are useful for including complex visualizations or interactive components:

  1. Create a new HTML file in the src/fragments/ directory, e.g., src/fragments/my-visualization.html
  2. Include it in your main document using {{{fragment-my-visualization}}}

Fragments can contain HTML, CSS, and JavaScript. They're loaded asynchronously, which helps keep your main document lightweight.

Advanced Customization

Styling

You can customize the appearance of your blog by editing src/style.css. The template uses CSS variables for colors, fonts, and spacing, making it easy to adjust the overall look and feel.

Adding JavaScript

For interactive components, add your JavaScript code to src/index.js or create new modules and import them. The template uses webpack to bundle JavaScript files.

Bibliography

Edit src/bibliography.bib to include your citations in BibTeX format.

Best Practices

Conclusion

This template gives you everything you need to create beautiful, interactive technical blogs. By combining clear writing with interactive visualizations and mathematical notation, you can effectively communicate complex ideas to your audience.

For more examples and inspiration, visit distill.pub.

Citation

For attribution in academic contexts, please cite this work as

"The Distill Blog Template", 2025.

BibTeX citation

@misc{distill_blog_template,
      title={The Distill Blog Template},
      author={Some Authors et al},
      year={2025},
}