Writing entries

Groups

Every entry belongs to a group. Every group can have its own template for rendering its entries, and in your site’s templates you can enumerate entries by group. For example, you may have a group “blog” and a group “pages”.

Directory structure

Sprokkel collects all files that end with the .dj file extension in ./entries/<group> directories. Entries can also be placed in their own directory to manage related assets such as images easily; for this case, Sprokkel looks for files named index.dj one directory deeper.

For example, the following are valid entry locations:

./entries
├── blog
│   ├── 2024-03-12-something
│   │   ├── index.dj
│   │   └── image.svg
│   └── 2024-04-24-something-else.dj
└── pages
    └── foobar.dj

Ordering and permalinks

Entries are sorted by their file names. Entries’ slugs are equal to their file names, but to aid custom ordering, anything up to and including the first underscore is dropped. If the part before the underscore can be parsed as a date (and optional time), it is used the entry’s publish date and time.

The date format is YYYY-MM-DD. The date plus time format is YYYY-MM-DDThhmmss. Time zones are not supported to ensure the lexicographical ordering of entries’ file names is equal to their chronological order of date and times. Consider hardcoding a specific timezone in the template instead.

Titles

If an entry starts with a level-1 heading, it is used as the entry’s title. For example, the following entry has title “Foo bar”. If no title is given, the slug is used as the entry’s title.

# Foo _bar_

Lorem ipsum...

Front matter

To customize some behavior and meta-information related to entries, use front matter.

Links

You can link between entries using their file names (without extensions). Sprokkel rewrites such links to the absolute URL of the target entry. For example:

In a [previous post](~/blog/2024-04-10_previous_post), ...

These internals links are recorded as a back-references in links’ target entries, and available in templates.