This post explains how to create new posts in the Astro AntfuStyle Theme and provides guidelines, tips, and tricks for writing posts.
Creating a New Post#
To create a new post, add a new .md
or .mdx
file in src/content/blog/
(see when to use MDX for enhanced Markdown features). Use a consistent naming scheme (lower-case, dashes instead of spaces), as the filename will be used as the path (slug).
You can organize posts directly under src/content/blog/
or in nested subdirectories (see Astro Routing Docs for more):
Choosing Between Markdown and MDX#
Use Markdown for simple posts with minimal interaction. You can also embed HTML and UnoCSS directly in Markdown, e.g.:
Use MDX if:
- You need to embed components.
- The content requires conditional rendering or dynamic data.
- You need interactive code examples or other highly interactive content.
MDX Support Limitations in RSS Generation
The theme automatically generates rss.xml
via src/pages/rss.xml.js
. When processing full post content, it uses the compiledContent()
helper to retrieve and sanitize the rendered HTML.
However, this feature does not support MDX files, which may result in the items.content
value not being generated as expected for posts written in .mdx
files.
Editing Frontmatter#
All .md
and .mdx
files in the src/content/blog/
belong to the blog
content collection.
Each post requires YAML frontmatter , which adds metadata at the top of Markdown/MDX files. The frontmatter fields for blog
posts are defined by schema: postSchema
in src/content/schema.ts
as follows:
Properties(* required) | Type(default) | Description |
---|---|---|
title * | string | Sets the post title, limited to 60 characters. This follows Moz’s recommendation, ensuring approximately 90% of titles display correctly in SERPs and preventing truncation on smaller screens or social platforms. |
subtitle | string ('' ) | Provides a post subtitle. If provided, it will be displayed below the title. If not needed, leave the field as an empty string or delete it. |
description | string ('' ) | Provides a brief description, used in meta tags for SEO and sharing purposes. If not needed, leave the field as an empty string or delete it, and the SITE.description will be used directly. |
pubDate * | z.coerce.date() | Specifies the publication date. See supported formats here. For example:"2023-01-10T00:00:00.000Z" "2023-01-10" "1/10/23" |
lastModDate | z.union([z.coerce.date(), z.literal('')]) | Tracks the last modified date. If not needed, leave the field as an empty string or delete it. |
minutesRead | number | Provides an estimated reading time in minutes. To auto-generate, delete the field; to hide it on the page, enter 0. |
radio | boolean (false ) | Indicates if the post includes audio content or links to an external audio source. If true , an icon will be added to the post item in the list. |
video | boolean (false ) | Indicates if the post includes video content or links to an external video source. If true , an icon will be added to the post item in the list. |
platform | string ('' ) | Specifies the platform where the audio or video content is published. If provided, the platform name will be displayed. If not needed, leave the field as an empty string or delete it. |
toc | boolean (true ) | Controls whether the table of contents (TOC) is generated for the post. |
share | boolean (true ) | Controls whether social sharing options are available for the post. |
ogImage | z.union([z.string(), z.boolean()]) ( true ) | Specifies the Open Graph (OG) image for social media sharing. To auto-generate OG image, delete the field or set to true . To disable it, set the field to false . To use a custom image, provide the full filename from /public/og-images/ . |
redirect | string | Defines a URL to redirect the post. |
draft | boolean (false ) | Marks the post as a draft. If true , it is only visible in development and excluded from production builds. |
The theme includes a VS Code snippet for auto-generating this frontmatter (located in .vscode/astro-antfustyle-theme.code-snippets
). Type postFrontmatter
and press tab
to insert it (tab completion is enabled in .vscode/settings.json
).
The Theme Supports Astro’s Intellisense in Content Files
Hovering over a property shows descriptions, and mismatches in types prompt warnings.
Formatting Post Titles
Auto-generated titles capitalize the first letter of each word. If you’ve tried editing the auto-generated frontmatter snippet, you’ll notice that the cursor reaches the title field last after tabbing through all others.
To correctly format titles according to The Chicago Manual of Style, you can use the Smart-Title-Case VS Code extension.
Writing the Post#
Once frontmatter is set, start writing your post!
To see how basic Markdown renders, refer to the Markdown Syntax Guide. To explore how to use MDX to enhance your flexibility in writing posts, check the MDX Docs and MDX in Astro.
Regardless of whether you’re using Markdown or MDX, don’t miss out on the Markdown/MDX extended features supported by this theme, including callouts (admonitions/alerts), fully-featured code blocks, image captions and links, video embeddings, styled GitHub links, and more.
Additionally, the title (set by the title
property in the YAML frontmatter) is automatically rendered as an h1. You don’t need to include the title again in the post, and it’s recommended to start with h2 headings.
Note that even if you configure FEATURES.toc[1].minHeadingLevel
in src/config.ts
to include 1
, the title set by the title
property won’t be included in the auto-generated TOC --- it only includes h1 headings written in the Markdown/MDX content.
Wrapping Up#
Here’s how to create a new post in the theme. Once completed, you can preview your post in real-time at /blog/if-stored-in-subdirectory/your-post-name
in your browser.
Happy writing, and may your content reach a wide and engaged audience! 🌎