Blog format
The blog folder
Which files a blog has, where posts, pages and episodes go, and how a path becomes an address.
Every blog is one folder. Only these files can exist in it:
| File | What it holds |
|---|---|
home.md | The home page: its title and text. Usually lists posts with ::posts. |
nav.md | The menu: one Markdown link per line, at most 20. |
footer.md | Text at the bottom of every page. |
post-header.md, post-footer.md, post-aside.md | Parts shown above, below or beside every post. |
social.md | Links to your other profiles, one Markdown link per line. |
blogroll.md | Blogs you recommend, one per line. See Blogroll. |
directories.md | Display names and order for folders of posts. |
redirects.md | Old addresses and where they go now. |
podcast.md | The podcast's show (Pro). See Podcast. |
styles.css | The blog's whole stylesheet. See Themes. |
posts/…/*.md | Articles, listed by date, in feeds and on the fediverse. |
pages/…/*.md | Pages such as About or Now: addressed, not listed. |
podcast/*.md | Podcast episodes (Pro), at /podcast/<name>. |
These names are fixed. Do not rename the site files, move them into folders, or create other files beside them: the blog reads exactly these. Only files under posts/, pages/ and podcast/ take names of your choosing. A file can be at most 1 MB. Anything else is refused, with the line that needs fixing.
Addresses#
An article or page is served at its path without the top folder and .md:
posts/reading-slowly.md→/reading-slowlyposts/trips/rome.md→/trips/rome, and the folder gets a listing at/tripspages/about.md→/about
File and folder names use letters and digits of any language, plus _ . ~ -. A path has at most 32 folders.
The blog keeps these addresses for itself: /archive, /feed, /rss.xml, /feed.json (also under /tags/<tag>/), /rss, /sitemap.xml, /robots.txt, /blogroll.opml, /.well-known/… and /podcast….
Links files#
nav.md, social.md and directories.md hold only Markdown links, one or more per line:
[About](/about)
[Archive](/archive)
[Notes](https://notes.example.com)
Menu links use https://. Links to other sites in the menu need Pro.
In directories.md, the link's address is the folder and its text is the name: [Travel](/trips).
Blogroll#
blogroll.md lists the blogs you read, one per line, in the order shown: the blog's name linked to its address, its feed as a second link named feed when it has one, then a few words about it if you like.
[Ana's notes](https://ana.example/) [feed](https://ana.example/feed.xml) Gardens and code.
[Ben writes](https://ben.example/)
Blog › Home › Blogroll fills these lines in for you: type a blog's address and it finds the name and the feed. A blogroll holds at most 200 blogs.
Place ::blogroll on any page to show the list. While it has blogs, feed readers can follow them all from /blogroll.opml (also at /.well-known/recommendations.opml), and every page links to it with <link rel="blogroll">.
Redirects#
redirects.md has one redirect per line: the old address, a space, then a path on this blog or an https:// address.
/2019/hello /hello
/old-about https://example.com/about
To keep a single article's old addresses, use its alias property instead (see Properties).
Drafts and unpublished changes#
A post, page or episode with publish: false is a draft: it has no address and nobody else sees it. Write creates drafts this way.
Once a file is published, edits made in Write are kept as unpublished changes beside it: readers see the published text until you choose Publish changes, or the changes are discarded. Every publish keeps a revision of the file, which you can restore later.
Bearletter · bearletter.com · Every page is also Markdown: llms.txt