Adding new posts in AstroPaper theme

Here are some rules/recommendations, tips & ticks for creating new posts in AstroPaper blog theme.

Table of contents

Creating a Blog Post

To write a new blog post, create a markdown file inside the src/data/blog/ directory.

Prior to AstroPaper v5.1.0, all blog posts had to be in src/data/blog/, meaning you couldn’t organize them into subdirectories.

Starting from AstroPaper v5.1.0, you can now organize blog posts into subdirectories, making it easier to manage your content.

For example, if you want to group posts under 2025, you can place them in src/data/blog/2025/. This also affects the post URL, so src/data/blog/2025/example-post.md will be available at /posts/2025/example-post.

If you don’t want subdirectories to affect the post URL, just prefix the folder name with an underscore _.

# Example: blog post structure and URLs
src/data/blog/very-first-post.md          -> mysite.com/posts/very-first-post
src/data/blog/2025/example-post.md        -> mysite.com/posts/2025/example-post
src/data/blog/_2026/another-post.md       -> mysite.com/posts/another-post
src/data/blog/docs/_legacy/how-to.md      -> mysite.com/posts/docs/how-to
src/data/blog/Example Dir/Dummy Post.md   -> mysite.com/posts/example-dir/dummy-post

💡 Tip: You can override a blog post’s slug in the frontmatter as well. See the next section for more details.

If the subdirectory URL doesn’t appear in the build output, remove node_modules, reinstall packages, and then rebuild.

Frontmatter

Frontmatter is the main place to store some important information about the blog post (article). Frontmatter lies at the top of the article and is written in YAML format. Read more about frontmatter and its usage in astro documentation.

Here is the list of frontmatter property for each post.

Tip! You can get ISO 8601 datetime by running new Date().toISOString() in the console. Make sure you remove quotes though.

Only title, description and pubDatetime fields in frontmatter must be specified.

Title and description (excerpt) are important for search engine optimization (SEO) and thus AstroPaper encourages to include these in blog posts.

slug is the unique identifier of the url. Thus, slug must be unique and different from other posts. The whitespace of slug should to be separated with - or _ but - is recommended. Slug is automatically generated using the blog post file name. However, you can define your slug as a frontmatter in your blog post.

For example, if the blog file name is adding-new-post.md and you don’t specify the slug in your frontmatter, Astro will automatically create a slug for the blog post using the file name. Thus, the slug will be adding-new-post. But if you specify the slug in the frontmatter, this will override the default slug. You can read more about this in Astro Docs.

If you omit tags in a blog post (in other words, if no tag is specified), the default tag others will be used as a tag for that post. You can set the default tag in the content.config.ts file.

export const blogSchema = z.object({
  // ...
  draft: z.boolean().optional(),
  tags: z.array(z.string()).default(["others"]), // replace "others" with whatever you want
  // ...
});src/content.config.ts

Sample Frontmatter

Here is the sample frontmatter for a post.

---
title: The title of the post
author: your name
pubDatetime: 2022-09-21T05:17:19Z
slug: the-title-of-the-post
featured: true
draft: false
tags:
  - some
  - example
  - tags
ogImage: ../../assets/images/example.png # src/assets/images/example.png
# ogImage: "https://example.org/remote-image.png" # remote URL
description: This is the example description of the example post.
canonicalURL: https://example.org/my-article-was-already-posted-here
---src/data/blog/sample-post.md

Adding table of contents

Adding table of contents