Markdown Tips and Tricks for Content Authors

Markdown is the backbone of content-driven websites. Astro supports the full CommonMark specification plus GitHub Flavored Markdown (GFM), giving you tables, task lists, strikethrough, and autolinks out of the box.

Frontmatter Best Practices

Every Markdown file in a content collection starts with YAML frontmatter. This is where you define metadata that gets validated against your Zod schema. Here are some best practices:

1. Always include a description — This helps with SEO and can be used in card previews
2. Use ISO 8601 dates — 2026-05-30 or 2026-05-30T14:30:00Z for precise timestamps
3. Keep tags consistent — Use a controlled vocabulary so filtering works reliably
4. Mark drafts explicitly — Use a draft: true field to filter out unpublished content

Code Blocks with Syntax Highlighting

Astro uses Shiki for syntax highlighting, which supports over 100 languages. You can specify the language after the triple backticks:

// Example: Fetching content in an Astro page
const posts = await getCollection('blog');
const sorted = posts.sort((a, b) => b.data.pubDate - a.data.pubDate);

You can also add a title to code blocks using the // syntax:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
  }),
});

Tables and Task Lists

GFM tables work naturally in Astro:

Feature	Supported	Notes
Tables	Yes	GFM extension
Task lists	Yes	Use - [ ] and - [x]
Strikethrough	Yes	Use ~~text~~
Autolinks	Yes	URLs are auto-linked

And task lists:

• Set up content collections
• Define schemas with Zod
• Create layouts and components
• Add MDX support for interactive components
• Implement search functionality

Images and Assets

Astro processes images in Markdown automatically. Place images in the public/ directory for static references, or co-locate them with your content files and use relative paths for optimized images through Astro’s image pipeline.

With these tips, you’ll be writing rich, well-structured content that looks great and is easy to maintain.