Astroのドキュメントを書く
Markdown/MDX/Markdoc
AstroとStarlightの環境ではMarkdownとMDX、拡張でMarkdocが使える。
MDXを使うとAstroやStarlightが準備したコンポーネントが使えるため、かなりリッチな表現ができる。ただし、Markdownからはかけ離れるため、魅力的ではあるものの、ドキュメントサイトとしては使用場面は限られる。
フロントマター
Jekyll等と同じく、フロントマターでメタデータを定義する。
title は必須。lastUpdated は最終更新日で true を指定するとGitから参照する。
title は h1 となるため、本文は ## （h2）からとするのが良い。
1
2
3
4
5
6
7
8
---
title: タイトル（h1）
lastUpdated: 2026-02-28 # trueだとGitの値を使用する
sidebar:
order: 3
---
## 本文の見出し（h2）
Markdownのシンタックス
基本的な構文は大体使える。タスクリスト（ * [ ] item ）なども使えるが、GitHubと完全に同じというわけではない。
シンタックスハイライト
Astroでは Shiki が採用されている。
対応している言語は以下を参照する。
少し変わった機能として言語IDに shell や console を指定するとコンソールの枠がレンダリングされる。
1
2
# this text is not copied
echo Hello,
そして、このコードブロックのコピーボタンでは、コメント行はコピーされないといった振る舞いをする。
画像
画像の保存場所は特に決まっておらず、Markdownファイルと同じディレクトリにおいても動作する。Jekyllでは assets フォルダに配置する必要があったが、そういった制限はない。共通の置き場所は src/assets となる。
src 以下に設置した画像ファイルはドキュメントのビルド時に変換される場合がある1。ビルド後の配置場所は dist/_astro/ でPNGはWebPになる。
public 以下にもファイルを配置できるが、こちらはfaviconなどドキュメント以外に必要な静的ファイルを配置する。
Alerts
CalloutsやAdmonitionsとも呼ばれる構文だが、Markdownでは対応しておらず、代替となる構文もない。
1
2
> [!NOTE]
> 非対応
使用したい場合は MDX か Markdoc での記述が必要で、MDX では Aside を使う。
1
2
import { Aside } from '@astrojs/starlight/components';
<Aside type="caution">警告</Aside>