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:

bundle install

To start the local development server with live rebuild:

bundle exec jekyll serve

Then open:

http://localhost:4000

To generate the static site once without running the server:

bundle exec jekyll build

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:

layout: post

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:

permalink: /:title/

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:

/introducing-fenn/

categories

Categories help group posts:

categories: announcements

Examples:

categories: tutorials
categories: releases
categories: announcements

author

The author field is optional:

author: blkdmr

The value must match an author slug from the _authors/ folder.

mathjax

Use this only if the post contains math:

mathjax: true

This enables math rendering for the page.

Write the post content

After the front matter, write your post in Markdown.

You can use headings:

## What fenn gives you

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:

_authors/blkdmr.markdown

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:

author: blkdmr

The post footer will automatically link to:

/authors/blkdmr/

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:

mathjax: true

Supported inline math formats:

$E = mc^2$

\(E = mc^2\)

Supported display math formats:

$$
E = mc^2
$$

\[
E = mc^2
\]

Jekyll’s Markdown engine, Kramdown, automatically converts $$...$$ blocks to \[...\], so both styles work.

Preview the post locally

Run:

bundle exec jekyll serve

Then open:

http://localhost:4000

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:

bundle exec jekyll build

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:

git push

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.