How to format a blog post

This page shows every way a post can look, next to the Markdown that makes it. Some of it happens on its own. The rest you ask for with a short line before and after a block.
Write the post in plain Markdown first. Then look at it on the preview and add a block where one would help a reader. Most posts need two or three, not all of them.
What happens on its own
When a post opens with a paragraph of 12 words or more, that paragraph is set a little larger, like the one at the top of this page. Once a post has four or more ## sections, each gets a number, and the contents box near the top lists them.
A few sections never get a number. Those are the ones with special names at the end of this page (questions, takeaways, references), and sections whose heading starts with “Conclusion”, “Final thoughts”, “Wrapping up”, “In closing”, “Related”, “More reading” or “More resources”.
A bullet list of 3 to 6 items, each starting with a label and 45 words or fewer, becomes a set of cards. A label is bold text of up to 9 words with more text after it, or up to 6 words and a colon:
- **Notice:** what the board sends before a meeting.
- **Agenda:** what the meeting will cover.
- **Minutes:** what the board decided.
- Notice: what the board sends before a meeting.
- Agenda: what the meeting will cover.
- Minutes: what the board decided.
A numbered list of 3 to 9 items that start with labels becomes a set of steps. It has to start at 1. Cards and steps stay a plain list when an item holds another list, a picture or a table.
1. **Set the date.** Check the notice period in your bylaws.
2. **Write the agenda.** Start with the standing items.
3. **Send the notice.** Keep a record of how it went out.
- Set the date. Check the notice period in your bylaws.
- Write the agenda. Start with the standing items.
- Send the notice. Keep a record of how it went out.
A quote of one paragraph and 45 words or fewer becomes a pull quote. A longer one stays a plain quote.
> Keep the records where the next board can find them.
Keep the records where the next board can find them.
A picture alone on its line becomes a figure. Text in quotes after the file name is the caption.


Tables scroll sideways on a phone instead of squeezing. A table with four or more columns uses the wider column, like this one:
| Meeting | Who comes | Notice | Minutes |
|---|---|---|---|
| Board meeting | The board, and owners who want to listen | As your bylaws say | Shared once the board approves them |
| Annual meeting | Every owner | Usually longer than for a board meeting | Approved at the next annual meeting |
:::wide gives the wider column to a smaller table or a picture.
Boxes you can add
Put :::name on the line before a block and ::: on the line after it. A title in square brackets after the name is optional. Settings go in curly brackets after that, like {time="20 minutes"} below.
:::summary[The short version]
- **Before:** send the notice on time.
- **During:** record each motion and vote.
- **After:** share the minutes.
:::
The short version
- Before: send the notice on time.
- During: record each motion and vote.
- After: share the minutes.
:::checklist[What to bring]
- The agenda
- Last meeting's minutes
- The budget
- Any bids to review
- A sign-in sheet
- The bylaws
:::
What to bring
- The agenda
- Last meeting’s minutes
- The budget
- Any bids to review
- A sign-in sheet
- The bylaws
A checklist with six items or more goes in two columns.
:::steps[Your first month]{time="20 minutes"}
1. **Find your bylaws.** Note the notice period.
2. **Pick a date.** Count back to the day the notice goes out.
3. **Write the agenda.** Keep it to one page.
4. **Send it.** Keep a copy of what went out.
:::
Your first month
Takes about 20 minutes
- Find your bylaws. Note the notice period.
- Pick a date. Count back to the day the notice goes out.
- Write the agenda. Keep it to one page.
- Send it. Keep a copy of what went out.
:::compare{warn}
### Post on the website
- Meeting dates
- The rules
- Approved minutes
### Never post
- Owners' phone numbers
- Bank account numbers
:::
Post on the website
- Meeting dates
- The rules
- Approved minutes
Never post
- Owners’ phone numbers
- Bank account numbers
Stories, dates and warnings
:::myth
"Nobody reads the minutes."
Owners look for them when something affects their home. Short, clear minutes get read.
:::
You may have heard
“Nobody reads the minutes.”
What's true
Owners look for them when something affects their home. Short, clear minutes get read.
{label="The facts"} after :::myth changes “What’s true” to your own words.
In a timeline, the bold part before the comma is the date, and the rest of it is the headline.
:::timeline[A year on the board]
- **January, Budget** The board adopts the budget.
- **April, Inspections** The board walks the common areas.
- **September, Bids** Vendors bid on next year's work.
- **November, Annual meeting** Owners elect the board.
:::
A year on the board
- JanuaryBudget The board adopts the budget.
- AprilInspections The board walks the common areas.
- SeptemberBids Vendors bid on next year’s work.
- NovemberAnnual meeting Owners elect the board.
:::tip[A tip]
Send the agenda with the notice, so owners know what will come up.
:::
A tip
Send the agenda with the notice, so owners know what will come up.
:::note and :::warning work the same way:
A note sits apart from the text around it, without asking for attention.
Be careful
Check your own bylaws before you rely on any example here.
Quotes and the product stripe
:::pullquote makes any quote large, even a long one. :::quote keeps a short one plain.
:::pullquote
> The minutes are the board's memory. When the next
> board asks why a rule changed, the minutes should tell
> them who moved it, who voted for it, and what the
> owners were told before the meeting.
:::
The minutes are the board’s memory. When the next board asks why a rule changed, the minutes should tell them who moved it, who voted for it, and what the owners were told before the meeting.
:::quote
> A short quote that should stay small.
:::
A short quote that should stay small.
Posts get product stripes on their own, between sections, picked to match what the post is about. To place one yourself, put a :::cta block where it should go. When a post has one, the automatic stripes stay out. feature picks which one, from src/data/promos.yaml: website, notices, meetings, vendors, records, votes, rules, budget or import.
:::cta{feature="votes"}
:::
A title and a paragraph in the block replace the stripe’s own headline and text. The screenshot and the button stay. Keep the words true to what the product does.
:::cta[Put the amendment to a vote.]{feature="votes"}
Owners vote online, one vote per lot, and the result is kept on file.
:::
A :::cta block has to stand on its own, not inside another block. To keep the stripes out of a post, add promos: false to its frontmatter. To choose them, list them: promos: [meetings, votes].
When you want none of it
Wrap a part in :::plain to stop the automatic formatting there, or add autoformat: false to the frontmatter to stop it for the whole post. The boxes you add still work.
:::plain
- **This list** stays a plain list.
- **Even though** its items start with labels.
- **It is** short, too.
:::
- This list stays a plain list.
- Even though its items start with labels.
- It is short, too.
Frequently asked questions
A section whose heading starts with “Frequently asked questions”, “FAQ” or “FAQs” turns each ### question into one that opens and closes. It needs two questions or more.
Can I break a post?
Not by formatting it. If a block name is wrong, the text still shows as plain Markdown, and the build lists the name it did not know.
Do I have to use any of this?
No. Plain Markdown looks good on its own. Add a block when it makes a post easier to read.
Key takeaways
A section whose heading starts with “Key takeaways”, “Takeaways”, “Summary”, “TL;DR”, “The bottom line”, “Bottom line” or “At a glance” sits in a box.
- Write plain Markdown first.
- Add two or three blocks where they help.
- Check the post on the preview before you publish.
References
A section whose heading starts with “References”, “Sources”, “Citations” or “Further reading” is set smaller.
A post can also bring its own contents list: a line that reads just “Table of contents” or “In this post”, followed by a list of links to the post’s headings. It then gets no numbers and no automatic box.
- This guide,
docs/editing.md, in the site’s repository.


