# The blog folder

Source: https://docs.bearletter.com/blog/folder

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](#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](/blog/podcast). |
| `styles.css` | The blog's whole stylesheet. See [Themes](/blog/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-slowly`
- `posts/trips/rome.md` → `/trips/rome`, and the folder gets a listing at `/trips`
- `pages/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:

```md
[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.

```md
[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.

```text
/2019/hello /hello
/old-about https://example.com/about
```

To keep a single article's old addresses, use its `alias` property instead (see [Properties](/blog/frontmatter)).

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