# Writing posts

Posts are written in Markdown. The editor — **My blogs → your blog → New post** — has a
**Preview** toggle that renders exactly what readers will see — the preview and
the published page go through the same renderer, so what you see really is what
you get.

## What Markdown supports

Headings, **bold**, *italic*, links, images, lists, tables, blockquotes,
horizontal rules, inline `code` and fenced code blocks.

````
```python
Post.objects.order_by("-published_at", "-id")
```
````

Fenced blocks keep their language label, so a downstream project can add syntax
highlighting without changing anything here.

## What it doesn't support, and why

**Raw HTML is shown as text, not rendered.** If you type `<div>` you will see
`<div>` on the page. This is deliberate: posts can be written by people and by
AI agents through the API, and a renderer that executes whatever HTML it is
given is the classic way a site ends up running someone else's JavaScript.
Links using `javascript:` or `data:` are stripped for the same reason.

If you need something Markdown can't express, put it in a template rather than
a post body.

## Titles and headings

Your post's title is already shown as the page heading, so you don't need to
repeat it. If the body opens with a heading identical to the title, it is
dropped automatically — handy when publishing a runbook page, where an opening
`# Heading` is the norm. A *different* opening heading is kept.

## The slug

The slug is the last part of the URL: `/blog/field-notes/my-post/`. Leave it
blank and it's derived from the title. A few words are reserved because the
blog's own URLs use them (`feed`, `tag`, `archive`, `search`, `subscribe`,
`newsletter`); if you pick one, a number is appended rather than the save
failing.

Changing the slug of a published post **breaks existing links**. There is a
permanent alternative that survives retitling: `/blog/p/<uid>/`, shown on the
post's detail page.

## Excerpt

The one- or two-sentence summary used in lists, feeds, search results, the
newsletter preview and link previews on social sites. Leave it blank and the
first paragraph is used.

## Cover image

JPEG, PNG, GIF or WebP, up to 5MB. **Alt text is required** when you set one —
a cover with no description is invisible to anyone using a screen reader, and
the form will not save without it.

## Tags

Comma-separated, created as you type them. Tags belong to one blog, so two
blogs can both have "ops" without sharing it. Each tag gets a page at
`/blog/<blog>/tag/<tag>/`.

## Publishing

A post is a **draft** until you publish it. On the post's page:

- **Publish now** — live immediately.
- **Schedule** — pick a date and time; a background job publishes it. (This
  needs a worker running; if one isn't, `/smallstack/status/` says so.)
- **Return to draft** — takes it off the site and the feeds.
- **Archive** — removes it from lists and feeds, but its URL keeps working for
  anyone who already linked to it.

While a post is unpublished, only you and staff can open its public URL, and
you'll see a **Draft preview** banner so there's no doubt about what a reader
would get. Everyone else gets a 404.