Writing a New Post
This tutorial will guide you on how to write a post in Astro-Chirpy. Even if you’re familiar with Astro, it’s worth reading as many features require specific frontmatter variables to be set.
Naming and Path
Create a new file named YYYY-MM-DD-TITLE.md and place it in the src/content/posts/ directory. The file extension must be .md (Markdown).
For example:
src/content/posts/2024-01-15-my-first-post.mdsrc/content/posts/2024-01-16-another-great-article.md
Front Matter
At the top of your post, you need to add frontmatter using YAML syntax:
---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORY, SUB_CATEGORY]
tags: [TAG] # TAG names should always be lowercase
---Unlike Jekyll, Astro doesn’t use layouts in frontmatter. The layout is determined by the content collection configuration.
Timezone of Date
To accurately record the release date of a post, provide the timezone in the date variable. Format: +/-TTTT, e.g. +0800.
Example:
---
date: 2024-01-15T14:30:00+08:00
---Categories and Tags
The categories of each post can contain up to two elements, and tags can have zero to infinity elements.
---
categories: [Blogging, Tutorial]
tags: [writing, astro, markdown]
---Author Information
Author information is configured in the src/data/authors.yml file. You can specify an author in your post’s frontmatter:
---
author: geocine
---To add a new author, edit src/data/authors.yml:
<author_id>:
name: <full name>
twitter: <twitter_of_author>
url: <homepage_of_author>{: file=“src/data/authors.yml” }
You can also specify multiple authors:
---
authors: [author1_id, author2_id]
---Including author information helps with SEO and social media sharing.
Post Description
By default, the first words of the post are used as the description for SEO and preview cards. You can customize this:
---
description: A concise summary of your post that appears in search results and social media.
---The description will also appear under the post title on the post’s page.
Table of Contents
By default, the Table of Contents (TOC) is displayed on the right panel of the post. To disable it for a specific post:
---
toc: false
---Comments
Comments are controlled globally through the site configuration. To disable comments for a specific post:
---
comments: false
---Media
Images, audio, and video are collectively referred to as media resources in Astro-Chirpy.
URL Prefix
You can define a URL prefix for media resources to avoid repetition:
-
For CDN hosting, configure the
cdnoption in your site config -
For post-specific media paths, use
media_subpathin frontmatter:--- media_subpath: /posts/my-post-images/ ---
The final resource URL is composed as: [cdn/][media_subpath/]file.ext
Images
Caption
Add italics to the next line of an image to create a caption:
_Image Caption_Size
Specify width and height to prevent layout shift:
{: width="700" height="400" }Abbreviated form (Chirpy v5.0.0+):
{: w="700" h="400" }For SVG images, you must specify at least the width.
Position
Control image alignment with classes:
-
Normal position (left-aligned):
{: .normal } -
Float to the left:
{: .left } -
Float to the right:
{: .right }
When using position classes, don’t add captions.
Dark/Light Mode
Provide different images for dark and light themes:
{: .light }
{: .dark }Shadow
Add shadow effect to images:
{: .shadow }Preview Image
Add a hero image at the top of your post (recommended resolution: 1200 x 630):
---
image:
path: /path/to/image
alt: image alternative text
---Simplified version:
---
image: /path/to/image
---LQIP
Low Quality Image Placeholders improve perceived performance:
For preview images:
---
image:
lqip: /path/to/lqip-file # or base64 URI
---For normal images:
{: lqip="/path/to/lqip-file" }Video Files
Embed video files directly using Astro components or HTML:
<video controls>
<source src="/path/to/video.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>Audio Files
Embed audio files:
<audio controls>
<source src="/path/to/audio.mp3" type="audio/mp3">
Your browser does not support the audio element.
</audio>Pinned Posts
Pin posts to the top of the home page (sorted by date):
---
pin: true
---Prompts
Create styled prompts with different types: tip, info, warning, and danger:
> Example line for prompt.
{: .prompt-info }Syntax
Inline Code
`inline code part`Filepath Highlight
`/path/to/a/file.extend`{: .filepath}Code Block
Create code blocks with triple backticks:
```
This is a plaintext code snippet.
```Specifying Language
Add syntax highlighting by specifying the language:
```javascript
const greeting = "Hello, World!";
console.log(greeting);
``````python
def greet():
print("Hello, World!")
```Line Numbers
By default, all languages except plaintext, console, and terminal display line numbers. To hide them:
```shell
echo 'No line numbers!'
```
{: .nolineno }Specifying the Filename
Display a filename instead of the language name:
```javascript
console.log("Hello");
```
{: file="src/scripts/hello.js" }Mathematics
Astro-Chirpy uses MathJax for mathematical expressions. Enable it per post:
---
math: true
---Then use the following syntax:
-
Block math with blank lines:
$$ E = mc^2 $$ -
Equation numbering:
$$ \begin{equation} E = mc^2 \label{eq:einstein} \end{equation} $$ Reference equation \eqref{eq:einstein} -
Inline math (no blank lines):
The equation $$ E = mc^2 $$ is famous. -
Inline math in lists (escape first
$):1. \$$ E = mc^2 $$ 2. \$$ F = ma $$
Mermaid
Mermaid creates diagrams from text. Enable it:
---
mermaid: true
---Then use mermaid code blocks:
```mermaid
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Debug]
D --> B
```Learn More
For more about Astro’s content collections and Markdown features, visit:
This Astro-Chirpy theme is based on the Jekyll Chirpy theme by Cotes Chung.