Altair docs
Blog
Write posts in Markdown. Altair adds the blog page, post pages, code highlighting, an RSS feed and the Writing section on the home page.
The blog is optional. While it has posts, Altair adds:
- a blog page at
/blog/, with posts grouped by year - a page for each post, with reading time, tags and links to the previous and next post
- an RSS feed at
/rss.xml - your latest posts in the Writing section of the home page
- a Blog link in the menu
Write a post
Create a Markdown file in src/content/posts/. The file name becomes the address: my-first-post.md is published at /blog/my-first-post/.
---
title: Designing for the second visit
description: First impressions get the attention, but people decide on the second visit.
date: 2026-09-12
tags: [Design, UX]
---
Your post starts here. Write in normal Markdown.
## A heading
A paragraph with **bold**, *italic* and a [link](https://example.com).| Field | Required | What it does |
|---|---|---|
title |
Yes | The post title. |
description |
Yes | One or two sentences, shown under the title, in the blog list, in search results and share cards. |
date |
Yes | Publication date, YYYY-MM-DD. Posts are sorted by it. |
updated |
No | Shows “Updated” with this date. |
cover |
No | A cover image, relative to the post, for example ../../assets/posts/cover.jpg. |
coverAlt |
No | A description of the cover for screen readers. |
tags |
No | A list of tags, shown on the post and in the blog list. |
draft |
No | true shows the post only while you run npm run dev. |
What you can use in a post
Everything in standard Markdown: headings, lists, links, images, quotes, tables and code. Altair styles each of them for comfortable reading. Look at the three sample posts for examples.
Code blocks
Add the language after the opening backticks to get syntax highlighting. The colors switch automatically with light and dark mode.
```js
const greeting = 'Hello';
```The highlighting themes are set in astro.config.mjs under markdown.shikiConfig. Any Shiki theme works.
Images in a post
Put the image in src/assets/posts/ and reference it relative to the post:
Astro optimizes images you reference this way.
Cover images
Covers appear full-width above the post. 1600×900 pixels works well. If the cover is a photo (JPG, PNG or WebP), it is also used as the post’s share image; otherwise the site’s share image is used.
The Writing section
The home page shows your newest posts together with any articles published elsewhere, newest first. Change how many appear with sections.writing.limit in src/site.config.ts. When you have posts, an “All posts” link leads to the blog page.
Blog text
The blog page title, its intro and the line at the end of each post come from blog in src/site.config.ts.
Turning the blog off
Delete the files in src/content/posts/. The blog page, the menu link and the posts in the Writing section disappear, and the RSS feed is empty. External articles in writing.yaml keep showing in the Writing section; empty that file too to hide the section completely.