This page explains how to create and publish a new post on the fenn blog.
Clone the blog repository
Fork the blog repository on GitHub, then clone your fork:
git clone https://github.com/<your-username>/blog.git
cd blog
The blog is built with Jekyll. Its Ruby dependencies are listed in the Gemfile, and bundle install installs them locally.
Set up the blog locally
Before writing or previewing posts, install the required Ruby gems:
To start the local development server with live rebuild:
Then open:
To generate the static site once without running the server:
The generated site will be available in the _site/ folder.
Create a new post file
All blog posts must be placed inside the _posts/ folder.
Create a new file using this naming format:
YYYY-MM-DD-title.markdown
For example:
2026-07-05-introducing-fenn.markdown
The date in the filename is important because Jekyll uses it to identify the post date.
Add the post front matter
Every post starts with a YAML front matter block.
Use this template:
---
layout: post
title: "Your post title"
date: 2026-07-05 12:00:00 +0200
categories: announcements
author: blkdmr
mathjax: false
---
Then write the post content below the front matter using Markdown.
Example:
---
layout: post
title: "Introducing fenn: a friendly environment for neural networks"
date: 2026-07-05 12:00:00 +0200
categories: announcements
author: blkdmr
mathjax: false
---
Every deep learning project seems to reinvent the same wheel: a config
parser, a logger, a training loop, and a README explaining how to run it all.
**fenn** exists so you do not have to write that scaffolding again.
Understand the main front matter fields
layout
Use:
This tells Jekyll to render the page as a blog post.
title
The title displayed on the blog page:
title: "Introducing fenn"
date
The publication date and time:
date: 2026-07-05 12:00:00 +0200
The date controls the sorting order of posts.
The blog uses this permalink style:
This means the post URL is based on the title slug, not the date.
For example, a post titled:
title: "Introducing fenn"
will become something like:
categories
Categories help group posts:
categories: announcements
Examples:
categories: tutorials
categories: releases
categories: announcements
author
The author field is optional:
The value must match an author slug from the _authors/ folder.
mathjax
Use this only if the post contains math:
This enables math rendering for the page.
Write the post content
After the front matter, write your post in Markdown.
You can use headings:
Lists:
- Auto-configuration
- Unified logging
- Trainers
- Templates
Code blocks:
```bash
pip install fenn
fenn list
fenn pull empty
```
Inline code:
Use the `fenn` CLI to pull templates.
Links:
Visit the [fenn GitHub repository](https://github.com/pyfenn/fenn).
Add an excerpt
The home page can show an excerpt for each post.
In _config.yml, the blog uses this setting:
excerpt_separator: "\n\n\n"
This means the excerpt is everything before the first triple-blank-line.
Example:
---
layout: post
title: "Introducing fenn"
date: 2026-07-05 12:00:00 +0200
categories: announcements
author: blkdmr
---
This short introduction will appear as the post excerpt on the home page.
The rest of the post starts here.
Make sure there are three blank lines between the excerpt and the rest of the article.
Add an author
Authors are stored in the _authors/ folder.
To add a new author, create a file like this:
The filename becomes the author slug.
Inside the file, use this structure:
---
layout: author
title: "Display Name"
role: "Optional role or title"
github: "https://github.com/handle"
---
A short bio written in Markdown.
Then reference the author in a post:
The post footer will automatically link to:
The author page will also automatically list the author’s posts.
Add math to a post
To use math, enable math rendering in the post front matter:
Supported inline math formats:
Supported display math formats:
Jekyll’s Markdown engine, Kramdown, automatically converts $$...$$ blocks to \[...\], so both styles work.
Preview the post locally
Run:
Then open:
Check that:
- the post appears on the home page;
- the title is correct;
- the author link works;
- code blocks render properly;
- math renders correctly, if used;
- the excerpt stops in the right place.
Build the site
Before publishing, run:
If the build completes without errors, the post is ready to publish.
Complete post template
You can copy this template when creating a new article:
---
layout: post
title: "Your post title"
date: 2026-07-05 12:00:00 +0200
categories: announcements
author: blkdmr
mathjax: false
---
Write a short introduction here. This can be used as the excerpt on the home page.
## Section title
Write your post content here.
## Another section
Add explanations, lists, images, code snippets, or math.
```bash
pip install fenn
```
## Conclusion
Close the post with a short summary or call to action.
Commit, push, and open a pull request
After checking that the site builds correctly, add and commit your changes:
git add _posts/YYYY-MM-DD-title.markdown
git commit -m "post: add YYYY-MM-DD-title.markdown"
For example:
git add _posts/2026-07-05-introducing-fenn.markdown
git commit -m "post: add 2026-07-05-introducing-fenn.markdown"
If you also added a new author file, include it in the same commit:
git add _posts/YYYY-MM-DD-title.markdown _authors/author-slug.markdown
git commit -m "post: add YYYY-MM-DD-title.markdown"
Push the changes to your fork:
Then open a pull request against the main pyfenn/blog repository.
Before opening the PR, make sure that:
- the post builds correctly with
bundle exec jekyll build;
- the post is in the
_posts/ folder;
- the filename follows
YYYY-MM-DD-title.markdown;
- the front matter is valid;
- any new author file is placed in
_authors/;
- the commit message follows the format
post: add YYYY-MM-DD-title.markdown.