07. AstroPaperのMarkdown表現とアセットの扱い

シリーズ目次 前章: 06. AstroPaperで記事を整理する：ディレクトリ・URL・タグ 次章: 08. AstroPaperの配色テーマをカスタマイズする

Table of contents

この章のねらい

AstroPaperの記事は素のMarkdownでも書けますが、テーマ側で拡張がいくつか組み込まれています。その記法と、画像などの素材をどこに置くかを見ていきます。

Markdownが表示されるまで

AstroPaperの astro.config.ts には、次のプラグインが登録されています。

markdown: {
  processor: unified({
    remarkPlugins: [
      remarkToc,
      [remarkCollapse, { test: "Table of contents" }],
    ],
    rehypePlugins: [rehypeCallouts],
  }),
  // ...
}astro.config.ts

• remark：Markdownの構造を扱う段階のプラグイン
• rehype：HTMLに近づいた構造を扱う段階のプラグイン

名前を覚える必要はありません。Markdownから中間形式、そこからHTMLという2段階があって、それぞれに拡張が挿さっている。これだけ分かれば足ります。

目次を自動生成する

記事本文に次の見出しを1行入れるだけで、それ以降の見出しから目次が作られます。

## Table of contents

そして remark-collapse の設定により、この目次は折りたたまれた状態で出ます。設定の test: "Table of contents" が、この文言の見出しを折りたたむという指定です。

読者がクリックすると開く形になるため、長い記事でも冒頭が目次で埋まりません。

test の値と見出しの文言が一致しないと折りたたまれません。日本語の見出しにしたい場合は astro.config.ts の test も合わせて変更する必要があります。

コールアウト（引用ボックス）

rehype-callouts により、引用の記法を拡張した「目立つ枠」が使えます。

> [!note]
> 補足情報をここに書きます。

> [!warning]
> ここで事故りやすい内容です。

> [!tip] 覚えておくと便利
> タイトルを指定することもできます。

[!種類] を引用の先頭に書くのが基本形です。よく使う種類は次のとおりです。

折りたたみ

種類のあとに - を付けると閉じた状態、+ を付けると開いた状態の折りたたみになります。

> [!note]- 長い補足（クリックで開く）
> 初期状態では閉じています。

見た目のテーマは src/styles/global.css で読み込まれています。

@import "rehype-callouts/theme/obsidian";src/styles/global.css

obsidian の部分を別のテーマ名に変えれば、枠の雰囲気を変更できます。

書き方は共通で、変えるのは種類の名前と折りたたみ記号だけです。

コードブロックの装飾

コードの色付けには Shiki が使われています。エディタと同じ配色エンジンなので、実際のエディタに近い見た目になります。

astro.config.ts では、ライトモードとダークモードで別々の配色が指定されています。

shikiConfig: {
  themes: { light: "min-light", dark: "night-owl" },
  defaultColor: false,
  wrap: false,
  transformers: [
    transformerFileName({ style: "v2", hideDot: false }),
    transformerNotationHighlight(),
    transformerNotationWordHighlight(),
    transformerNotationDiff({ matchAlgorithm: "v3" }),
  ],
}astro.config.ts

この transformers により、4つの便利な記法が使えます。

ファイル名ラベル

コードブロックの言語のあとに file="..." を書くと、左上にファイル名が表示されます。

```ts file="src/config.ts"
const value = 1;
```

この記法はAstroPaper独自のもので、実装は src/utils/transformers/fileName.js にあります。どのファイルの話なのかを明示できるので、解説記事では使わない手はありません。

行の強調

強調したい行の末尾にコメントで [!code highlight] と書きます。

```ts
const a = 1;
const b = 2; 
```

単語の強調

[!code word:単語] と書くと、以降の行でその単語が強調されます。

```ts
import config from "@/config";
console.log(config.site.title);
```

差分表示

[!code ++] と [!code --] で、追加行と削除行を色分けできます。

```ts
const oldValue = 1; 
const newValue = 2; 
```

変更前と変更後を並べて説明するときに読みやすくなります。

コピーボタン

すべてのコードブロックには、右上にコピーボタンが自動で付きます。これは記事ページのスクリプトが実行時に追加しているもので、記事側で何かを書く必要はありません。

4つの記法を書き方の実例とともに並べておきます。

画像の扱い

置き場所の使い分け

src/ 側に置いてください。Astroが自動でサイズと形式を最適化して、読み込みを速くしてくれます。

記事からの参照

Markdownの画像記法は、感嘆符・角かっこ・丸かっこの3つを組み合わせた形です。角かっこには代替テキスト、丸かっこには画像の場所を書きます。

丸かっこに書くパスは、置き場所によって次のように変わります。

この章の冒頭にある処理の流れの図も、記事と同じディレクトリの ./assets/markdown-pipeline.svg を相対パスで参照しています。

置き場所・書くパス・最適化の有無をまとめると次のとおりです。

代替テキストを必ず書く

角かっこの中身は代替テキストです。画像が表示できないときに代わりに読まれ、読み上げソフトもここを読みます。

• 悪い例：代替テキストが画像、図だけ
• 良い例：代替テキストが「設定ファイルの値が各ページへ届くまでの流れを示した図」

その画像が何を伝えているかを書いてください。何の画像かではありません。テーマ側がアクセシビリティを整えているのに、記事側で崩したらもったいない。

画像の拡大表示

記事内の画像はクリックすると拡大表示されます。この機能も記事ページのスクリプトが自動で有効にするため、記述は不要です。キーボードの Enter や Space でも開き、Esc で閉じられます。

表の扱い

Markdownの表はそのまま使えます。列が多いと横にはみ出すことがあるので、内容は詰め込みすぎないでください。

より柔軟に表を扱いたい場合は、テーマに ResponsiveTable というコンポーネントが用意されています。ただしこれはコンポーネントなので、次に説明するMDXでのみ使えます。

MDXを使う

拡張子を .mdx にすると、Markdownの中にコンポーネントを埋め込めるようになります。

---
title: "MDXの例"
description: "コンポーネントを埋め込んだ記事です。"
pubDatetime: 2026-08-02T09:00:00.000Z
---

import ResponsiveTable from "@/components/ResponsiveTable.astro";

通常のMarkdownがそのまま書けます。

<ResponsiveTable variant="striped">

| 項目 | 説明 |
| --- | --- |
| A | 1つ目 |
| B | 2つ目 |

</ResponsiveTable>src/content/posts/sample.mdx

ResponsiveTable は表を横スクロール可能な枠で囲むコンポーネントで、variant に "minimal"、"striped"、"striped-minimal" を指定して見た目を変えられます。

.md と .mdx のどちらも記事として同じように扱われるので、必要な記事だけMDXにするという使い分けができます。

MDXでは { と } がプログラムの記法として解釈されます。文章中で中かっこをそのまま書きたいときに面倒なので、理由がなければ .md にしてください。

できることと、その引き換えに背負う制約を並べます。

要点

• ## Table of contents と1行書くだけで、折りたたまれた目次が自動生成される。
• > [!note] のような記法でコールアウトが使え、- や + を添えると折りたたみになる。
• コードブロックでは file="..." によるファイル名表示と、[!code highlight] / [!code ++] / [!code word:...] の記法が使える。
• 記事の画像は原則 src/ 側に置いて最適化させ、public/ はファビコンなど加工されたくないファイルに限る。
• コンポーネントを埋め込みたい記事だけ .mdx にすればよく、.md と混在できる。

参考資料

• テンプレート同梱ソース astro.config.ts — remark / rehype / Shikiの設定
• テンプレート同梱ソース src/utils/transformers/fileName.js — file="..." の実装
• rehype-callouts — コールアウトの記法とテーマ
• remark-toc — 目次の自動生成
• Shiki Transformers — [!code ...] 記法の一覧
• Astro: Markdown & MDX — Markdown処理とMDXの利用
• Astro: Images — 画像の置き場所と最適化

シリーズ目次 前章: 06. AstroPaperで記事を整理する：ディレクトリ・URL・タグ 次章: 08. AstroPaperの配色テーマをカスタマイズする