This guide covers the rules and conventions for creating new posts in AstroPaper — file placement, frontmatter fields, images, and syntax highlighting.
Photo by{” ”}
Pixabay
Table of contents
Open Table of contents
Creating a Blog Post
To write a new blog post, create a markdown (or MDX) file inside the src/content/posts/ directory.
You can organize posts into subdirectories to make content easier to manage. The subdirectory name becomes part of the post URL. For example, src/content/posts/2025/example-post.md will be available at /posts/2025/example-post.
If you want a subdirectory for organization only, without it affecting the URL, prefix the folder name with an underscore (_).
# Example: post file paths and their URLs
src/content/posts/very-first-post.md -> mysite.com/posts/very-first-post
src/content/posts/2025/example-post.md -> mysite.com/posts/2025/example-post
src/content/posts/_2026/another-post.md -> mysite.com/posts/another-post
src/content/posts/docs/_legacy/how-to.md -> mysite.com/posts/docs/how-to
src/content/posts/Example Dir/Dummy Post.md -> mysite.com/posts/example-dir/dummy-postFiles and directories prefixed with _ are excluded from routing. Use them for drafts, shared assets, or internal-only content.
Frontmatter
Frontmatter is the main place to store metadata about a blog post. It lives at the top of the file in YAML format. Read more about frontmatter and its usage in Astro documentation.
Here is the list of frontmatter properties for each post:
| Property | Description | Remark |
|---|---|---|
| title | Title of the post. (h1) | required* |
| description | Description of the post. Used in post excerpt and site description of the post. | required* |
| pubDatetime | Published datetime in ISO 8601 format. | required* |
| modDatetime | Modified datetime in ISO 8601 format. (only add this property when a blog post is modified) | optional |
| author | Author of the post. | default = site.author |
| featured | Whether or not to display this post in the featured section of the home page. |
…