BearletterDocsllms.txtbearletter.comDashboard

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:

FileWhat it holds
home.mdThe home page: its title and text. Usually lists posts with ::posts.
nav.mdThe menu: one Markdown link per line, at most 20.
footer.mdText at the bottom of every page.
post-header.md, post-footer.md, post-aside.mdParts shown above, below or beside every post.
social.mdLinks to your other profiles, one Markdown link per line.
blogroll.mdBlogs you recommend, one per line. See Blogroll.
directories.mdDisplay names and order for folders of posts.
redirects.mdOld addresses and where they go now.
podcast.mdThe podcast's show (Pro). See Podcast.
styles.cssThe blog's whole stylesheet. See Themes.
posts/…/*.mdArticles, listed by date, in feeds and on the fediverse.
pages/…/*.mdPages such as About or Now: addressed, not listed.
podcast/*.mdPodcast 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:

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….

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