Adding new posts in astro-minimax theme

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

Quick create: Use the CLI to quickly create posts: astro-minimax post new "Post Title" or astro-minimax post new "Title" --lang=en.

Path note: If you’re using the GitHub Template method, the blog content directory is at apps/blog/src/data/blog/. If using CLI or NPM package integration, it’s at src/data/blog/ in your project root.

Creating a Blog Post

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

astro-minimax supports organizing blog posts into subdirectories for easier content management.

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 astro-minimax 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.

const blog = defineCollection({
  // ...
  schema: z.object({
    // ...
    tags: z.array(z.string()).default(["others"]), // replace "others" with whatever you want
    // ...
  }),
});

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
category: Tutorial/Blog
tags:
  - some
  - example
  - tags
cover: ../../../assets/images/example.png # Cover image for cards and article banner
ogImage: ../../../assets/images/example.png # OG image for social sharing (optional, auto-generated if not set)
# 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
---

Cover Image vs OG Image

The cover and ogImage fields in the frontmatter serve different purposes:

• cover — Cover image for post cards and article banners. Supports local image paths or remote URLs.
• ogImage — Social sharing image for Twitter, Facebook, and other platforms. Supports local image paths or remote URLs.

Fallback Behavior

Image display follows this priority:

1. cover is set → use cover for cards and banners
2. No cover, but ogImage is set → ogImage is used as the cover image as well
3. Neither is set → a dynamic OG image is auto-generated at build time, used for both cover and social sharing

Headings

There’s one thing to note about headings. The astro-minimax blog posts use title (title in the frontmatter) as the main heading of the post. Therefore, the rest of the heading in the post should be using h2 ~ h6.

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

Syntax Highlighting

astro-minimax uses Shiki for syntax highlighting, enhanced with @shikijs/transformers for better fenced code blocks. If you don’t want to use it, you can remove it from astro.config.ts like this

pnpm remove @shikijs/transformers

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

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkMath, remarkGithubAlerts, remarkEmoji, remarkReadingTime],
    shikiConfig: {
      // For more themes, visit https://shiki.style/themes
      themes: { light: "min-light", dark: "night-owl" },
      defaultColor: false,
      wrap: false,
      transformers: [
        transformerFileName(),
        transformerNotationHighlight(),
        transformerNotationWordHighlight(),
        transformerNotationDiff({ matchAlgorithm: "v3" }),
      ],
    },
  },
  // ...
}

Storing Images for Blog Content

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

Note! If it’s a requirement to style optimized images in markdown you should use MDX.

Inside src/assets/ directory (recommended)

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

You can use relative path or alias path (@/assets/) to serve 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 ❌ -->
<img src="@/assets/images/example.jpg" alt="something">
<!-- ^^ This is wrong -->

Technically, you can store images inside any directory under src. In here, src/assets is just a recommendation.

Inside public directory

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

For these images, you should use an absolute path; and these images can be displayed using markdown annotation or 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

When you put images in the blog post (especially for images under public directory), it is recommended that the image is compressed. This will affect the overall performance of the website.

My recommendation for image compression sites.

• TinyPng
• TinyJPG

OG Image

The default OG image will be placed if a post does not specify the OG image. Though not required, OG image related to the post should be specify in the frontmatter. The recommended size for OG image is 1200 X 640 px.

If ogImage is not specified in frontmatter, astro-minimax auto-generates it at build time. See Dynamic OG Images.