This guide covers the rules and conventions for creating new posts in AstroPaper — file placement, frontmatter fields, images, and syntax highlighting.

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-post

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:

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 you to include these in all blog posts.

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 src/content.config.ts:

// ...
tags: z.array(z.string()).default(["others"]), // replace "others" with whatever you want
// ...src/content.config.ts

Sample Frontmatter

Here is sample frontmatter for a post.

---
title: The title of the post
author: your name
pubDatetime: 2022-09-21T05:17:19Z
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/content/posts/sample-post.md

VS Code snippets (optional)

AstroPaper includes workspace snippets to speed up creating new posts:

• frontmatter: inserts the recommended frontmatter block
• template: inserts a basic post template (including ## Table of contents)

These snippets live in .vscode/astro-paper.code-snippets. If you use VS Code (or Cursor), they should be available automatically when you open the workspace.

Callouts

AstroPaper started supporting callouts in AstroPaper v6.1. They use a simple blockquote syntax powered by rehype-callouts (Obsidian theme).

Here are the most commonly used types:

The full list of supported types includes: NOTE, ABSTRACT, INFO, TODO, TIP, SUCCESS, QUESTION, WARNING, FAILURE, DANGER, BUG, EXAMPLE, QUOTE — each with its own icon and color. Many types also accept aliases (e.g. HINT and IMPORTANT for TIP, CAUTION for WARNING). See the rehype-callouts docs for the complete reference.

Collapsible callouts

Add - after the type to make the callout collapsed by default, or + to make it expanded but collapsible:

Custom titles

Replace the default type label with any title you like by adding text after the type:

Syntax summary

> [!NOTE]
> Supplementary information.

> [!WARNING]- Collapsed by default
> Hidden until expanded.

> [!TIP]+ Expanded, but collapsible
> Starts open.

> [!DANGER] Custom title
> Replaces the default heading.

Adding table of contents

By default, a post does not include any table of contents (TOC). To include one, write Table of contents as an h2 heading (## in Markdown) and place it where you want it to appear:

---
# frontmatter
---

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

## Table of contents

<!-- the rest of the post -->

Headings

There’s one thing to note about headings. AstroPaper blog posts use title (from frontmatter) as the main heading of the post. Therefore, the rest of the headings in the post should use h2 ~ h6.

This rule is not mandatory, but highly recommended for visual, accessibility, and SEO purposes.

Syntax Highlighting

AstroPaper uses Shiki as the default syntax highlighter, with @shikijs/transformers for enhanced fenced code blocks. If you don’t want to use the transformers, you can remove them:

pnpm remove @shikijs/transformers

// ...
import {
  transformerNotationDiff,
  transformerNotationHighlight,
  transformerNotationWordHighlight,
} from "@shikijs/transformers";

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkToc, [remarkCollapse, { test: "Table of contents" }]],
    shikiConfig: {
      themes: { light: "min-light", dark: "night-owl" },
      defaultColor: false,
      wrap: false,
      transformers: [
        transformerFileName(),
        transformerNotationHighlight(),
        transformerNotationWordHighlight(),
        transformerNotationDiff({ matchAlgorithm: "v3" }),
      ],
    },
  },
  // ...
});astro.config.ts

Storing Images for Blog Content

Here are two methods for storing images and using them inside a markdown file.

Inside src/assets/ directory (recommended)

You can store images inside the src/assets/ directory. These images will be automatically optimized by Astro through the Image Service API.

You can use a relative path or alias path (@/assets/) to reference these images.

Example: suppose you want to display example.jpg whose path is src/assets/images/example.jpg.

![something](@/assets/images/example.jpg)

<!-- OR -->

![something](../../assets/images/example.jpg)

<!-- Using img tag or Image component won't work in markdown ❌ -->
<img src="@/assets/images/example.jpg" alt="something">
<!-- ^^ This is wrong -->

Inside public/ directory

You can store images inside the public/ directory. Keep in mind that images stored in public/ remain untouched by Astro, meaning they will be unoptimized and you need to handle image optimization yourself.

For these images, use an absolute path. They can be displayed using markdown image syntax or an HTML img tag.

Example: assume example.jpg is located at public/assets/images/example.jpg.

![something](/assets/images/example.jpg)

<!-- OR -->

<img src="/assets/images/example.jpg" alt="something">

Bonus

Image compression

Recommended image compression sites:

• TinyPng
• TinyJPG

OG Image

The default OG image will be used if a post does not specify one. Though not required, an OG image relevant to the post should be specified in the frontmatter. The recommended size for OG images is 1200 X 640 px.