Topic Format

Topics are the skeleton of this website since most content is attached to one in one way or another. The file format for topics is a simple subset of Markdown that relies on element order and decoration to add additional information to the topic processor.

Format Details

Slugs

A topic’s slug is most often defined using its file name. File names, for topics, use an extension .topic.md. For example, the now topic file name, having a slug of topic-format, would be topic-format.topic.md. Like all other derived data, the topic’s slug can be overwritten using frontmatter or a sidecar file.

Titles

Topic titles are derived from an <h1> tag at the very top of the document (right below the frontmatter, if there is any). The <h1> tag is removed from the topic’s main content unless it is the only piece of content within the topic’s file.

Lead-Ins

A topic can, optionally, define a lead-in, which can be displayed outside of the topic’s main content. If the first paragraph in the document—after the title <h1>—is followed by a <hr> tag, it is considered the topic’s lead-in. Like the title, the topic’s lead-in will be pulled out of the main content—along with the <hr>—tag, and the processed content will be available in the topic’s data.

Timestamps

A topic’s timestamps are derived from the website’s git history. Its created at timestamp is determined from the time that the topic’s main file first showed up in the repository while the updated at timestamp is from the date of the file’s last commit.

Linking & Tagging Topics

Topics can be linked together using tags. Tags are formatted as hashtags and live in the last <p> of the topic’s document if preceded by a <hr> tag. Tags are removed from the processed content. Suppose the first tag of the topic is the same as another topic’s slug. In that case, it is considered the parent topic of that particular topic.

Outgoing topic links are also extracted from the content of the topic so forward and back links can processed and kept track of.