How to Write Articles in Astro

Astro provides a powerful content management system that makes creating and managing blog articles simple and efficient. This guide details how to create and publish articles in your Astro project.

Article File Structure

Storage Location

All articles should be stored in the src/content/blog/ directory. Astro automatically scans this directory for Markdown files and converts them to blog articles.

File Naming Conventions

• Use lowercase letters and hyphens in filenames, e.g., my-first-post.md
• The filename becomes the article’s URL path, so make it meaningful and concise
• Avoid spaces and special characters

Front Matter Configuration

Each article must begin with Front Matter — YAML-formatted metadata enclosed by three dashes:

---
title: "Article Title"
description: "Article description"
publishDate: 2025-12-26
tags: ["tag1", "tag2"]
image: "/path/to/image.jpg"
---

Required Fields

title: Article title

• Displayed on the article page and blog listing
• Supports HTML entities and special characters

description: Article description

• Briefly summarizes the article content, typically 1-2 sentences
• Used for SEO and social media sharing

publishDate: Publication date

• Format: YYYY-MM-DD
• Used for article sorting and archiving
• Only articles with publish dates no later than the current date are displayed

Optional Fields

tags: Array of tags

• Used for article categorization and tag cloud
• Format: [“tag1”, “tag2”, “tag3”]
• Can be omitted; articles will display no tags

image: Article cover image

• Image path is relative to the public/ directory
• Recommended size: 1200x630 pixels (optimized for social media sharing)
• Supports JPG, PNG, WebP, and other formats

Markdown Content Writing

Basic Syntax

# Heading 1
## Heading 2
### Heading 3

**Bold text** and __bold text__
*Italic text* and _italic text_
***Bold italic text***

- Unordered list item 1
- Unordered list item 2
  - Nested list item
  - Another nested item

1. Ordered list item 1
2. Ordered list item 2

[Link text](https://example.com)

![Image description](/path/to/image.jpg)

Code Blocks

Inline code: const variable = 'value';

Code blocks:

function greet(name) {
  console.log(`Hello, ${name}!`);
}

Syntax-highlighted code blocks:

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

Blockquotes and Tables

This is blockquote text Can have multiple lines

Column 1	Column 2	Column 3
Data 1	Data 2	Data 3
Data 4	Data 5	Data 6

Image Handling

Image Storage Location

• All static assets should be placed in the public/ directory
• Consider creating subdirectories in public/, e.g., public/images/blog/

Image Reference Methods

In Front Matter:

image: "/images/blog/my-article-cover.jpg"

In article content:

![Image description](/images/blog/my-article-image.jpg)

Image Optimization Tips

• Use WebP format for better compression
• Provide multiple image sizes for different devices
• Add meaningful alt text to images for accessibility

Article Publishing Process

1. Create Article File

Create a new .md file in the src/content/blog/ directory

2. Write Front Matter

Fill in the required metadata

3. Write Article Content

Use Markdown syntax for the article body

4. Preview and Test

Run npm run dev to start the development server and preview articles in the browser

5. Publish Article

Articles will automatically appear on the blog listing page without additional configuration

Best Practices

Content Organization

• Use clear article structure with appropriate heading levels
• Keep each paragraph focused on a single point
• Use lists, tables, and images to enhance readability

SEO Optimization

• Include relevant keywords in titles and descriptions
• Use H1, H2, H3 headings appropriately
• Add meaningful alt text to all images

Code Examples

• Use syntax highlighting to improve code readability
• Provide complete, runnable code examples
• Add explanations and comments for complex code

FAQ

Q: Articles aren’t showing in the blog listing? A: Check if publishDate is set to a future date; Astro won’t display articles scheduled for future publication.

Q: Images aren’t displaying? A: Ensure image paths are correct and start with /, and the image file actually exists in the public/ directory.

Q: Tag clicks aren’t working? A: Tag page functionality may require additional implementation; check your route configuration.

Q: How to set article author? A: You can add an author field in Front Matter and display it in your template.

By following this guide, you can easily create professional blog articles in Astro. Remember, good content requires not only technical implementation but also valuable thinking and expression.