This page brings together examples of Astro’s built-in Markdown and MDX enhancements.
Content organization
| Directory | Purpose |
|---|---|
content/posts/ | Articles |
content/pages/ | Standalone pages and builtin page introductions |
Use a Markdown or MDX file for a simple entry. Create a folder with index.md or index.mdx when an article needs colocated images, components, or attachments. A post’s slug sets its address; for example, slug: demos produces /en/posts/demos/ with the default language-prefix policy.
Posts require a title and publication date. Other useful fields include a description, tags, and a cover image:
title: An example articleslug: exampledate: 2026-01-01description: Introduce the article in one sentence.tags: [astro, content]image: ./cover.webpfeatured: trueBundle images and attachments
Relative paths let you keep article assets beside the content. The cover and examples below are included as attachments in this post bundle.

Example attachments: plain text, Python code, an HTML page, a Markdown file, and an archive.
Article display options
Choose which article details to show globally in article.display, then override individual entries with the display frontmatter field.
| Field | Displayed content |
|---|---|
title | Title, description |
author | Author |
published | Publication date |
updated | Last update |
tags | Tags at the bottom |
share | Share button and panel |
navigation | Previous and next articles |
All options are enabled by default. When updated is provided and differs from the publication date, the last update appears at the bottom of the article. To hide only the author on one entry, for example:
display: author: falseOther fields inherit the global settings. Standalone pages support the same display options.
Markdown and MDX enhancements
Callouts
Create a callout with markers such as > [!NOTE] or > [!TIP]. Add a custom title after the marker.
Expressive Code blocks
type Reader = { name: string };const reader: Reader = { name: 'BlogGPT' };
function greeting({ name }: Reader) { return `Hello, ${name}!`;}pnpm checkpnpm buildKaTeX math
Inline math such as appears alongside text. Surround display math with $$:
Mermaid diagrams
Write a diagram in a code block marked mermaid:
flowchart LR A[Write content] --> B[Preview locally] B --> C[Build the site] C --> D[Publish]Image lightbox
Click an image to view it at full size. Zoom, switch images, or press Escape to close the lightbox.


Interactive MDX components
Adjust the sine wave’s amplitude, period, and initial phase with the sliders. Use arrow keys for smaller adjustments, or click Reset to restore the initial values.
y = 1.0 sin(2πx / 6.28 + 0.00)
Import an Astro component into an .mdx file, then place it in the body. This demo keeps the component and calculation helper under article-enhancements/ in its bundle:
import SineWave from './article-enhancements/SineWave.astro';
<SineWave lang="en" />Keep one-off components in their article bundle, or write simple markup directly in MDX. Put components shared by multiple articles in custom/components/ and import them using relative paths.
Per-entry enhancement switches
Set global defaults for enhancements under article in blog.config.ts. Outlines use toc.enabled, and automatic share covers use shareCover.enabled. An article or standalone page can override only the fields it needs:
math: truemermaid: falselightbox: truecallouts: truetoc: trueshareCover: falsetrue enables a feature, false disables it, and omitted fields inherit global settings. Available switches are math (KaTeX), mermaid (diagrams), lightbox (image zoom), callouts, toc (article outline), and shareCover (automatic social image). Disabling math, diagrams, or callouts displays their source or a plain quotation; disabling automatic share covers uses the configured article cover.
Find an article
The homepage and search panel both find content. The default scope is “Articles”; “Titles” includes only article titles and descriptions, “Body” includes only article bodies, and “Everywhere” includes articles, tags and standalone pages.
Body matches include surrounding context. Click a passage to jump to the matching paragraph.
Complete commands and articles
Type / to show matching commands, or @ to complete titles from all public articles.
| Command | Action |
|---|---|
/random | Open a random recent public article |
/lang en | Switch the interface language |
/theme dark | Change appearance; light and system are also available |
/status | Open blog statistics |
/archives | Open the archives |
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Ctrl+K / ⌘+K | Open search |
Ctrl+Shift+S / ⌘+Shift+S | Toggle the sidebar |
Ctrl+Shift+O / ⌘+Shift+O | Return home |
Shift+Esc | Focus the homepage input |
Ctrl+/ / ⌘+/ | View keyboard shortcuts |
Resize the sidebar by dragging its edge, or using arrow keys when the resize control is focused.
Site statistics
Open statistics from the bottom-left author menu or by entering /status in the homepage input.
Dates and publication states
| Setting | Publication behavior |
|---|---|
| Publication date reached | Published and included in lists and search |
draft: true | Saved as a draft for development preview |
| Future date | Published when rebuilt after the date is reached |
hidden: true | Direct address remains available; omitted from lists and search |
date sets publication time, and updated sets the last update. Common date aliases are also supported for migration. See Frontmatter.
Organize existing content
Place Markdown / MDX files in content/posts/, with images and attachments managed in bundles. Convert the previous system’s shortcodes and template tags to Markdown, HTML or MDX. Tags link through slugs. See Content and feature examples for the file layout.
Deploy and update
For automatic blog builds and deployments, connect a Git repository to Vercel (recommended):
- Push the theme source to your own Git repository and import it into Vercel.
- Select
Astrofor Framework Preset and keep Root Directory at the repository root. - Set Install Command to
pnpm install --frozen-lockfile, Build Command topnpm buildand Output Directory todist. Select Node.js24.xand addENABLE_EXPERIMENTAL_COREPACK=1to the Production and Preview environment variables. - Set
site.baseUrlto the production domain, commit the configuration and deploy. Later pushes to the production branch automatically rebuild and update the site; use other branches for previews.
pnpm build generates bundled attachments, share covers and Pagefind search indexes. Trigger another build when a scheduled article reaches its publication date. Other static hosts can also publish the complete dist/ directory with directory indexes and a 404 page.
See Build and deploy for the full steps.

