---
title: コピペで試せるMarkdown記事の実践テンプレート
slug: markdown-feature-showcase
description: 読者が迷わず再現できる技術記事を題材に、コマンド、検証、トラブル対応まで含めたMarkdownの実践例を紹介します。
publishedAt: 2026-07-08
updatedAt: 2026-08-27
draft: false
tags:
  - '2026'
  - blog
  - markdown
  - template
heroImage: ../assets/sample-image.jpg
---

Markdownの機能確認だけなら、見出し、表、画像を一つずつ並べれば済む。しかし、実際の技術記事で大切なのは、記法の数よりも**読者が途中で迷わず、結果を自分で確かめられること**だ。

この記事は、このブログで使えるMarkdownを見せながら、そのまま執筆時のチェックリストとして使える形にした。コマンド右上の「コピー」を押すと、プロンプト記号を含まないコマンドだけをコピーできる。

元の記法を確認したい場合は、[この記事のRaw Markdownを開く](https://blog.kinn-kinn.com/blog/markdown-feature-showcase.md)。このサイトでは、公開記事のURL末尾に `.md` を付けると、frontmatterを含む原稿をプレーンテキストで読める。

> この記事のゴール: 新しい記事を作り、ローカルで表示を確認し、公開前の検証までを再現できるようにする。

## 先に結論

再現しやすい技術記事には、少なくとも次の情報が必要になる。

- 対象バージョンと作業ディレクトリ
- そのままコピーできる、1操作単位のコマンド
- 成功したと判断できる期待結果
- 変更内容を確かめる検証コマンド
- 失敗したときの確認場所と、安全な戻し方

「実行できた」と「正しくできた」は別なので、操作と検証をセットで書くのがポイントだ。

## 0. 前提条件を固定する

この記事の例は、このブログのrepository直下で実行する。必要な環境は次のとおり。

| 項目 | 条件 | 確認コマンド |
| --- | --- | --- |
| Node.js | 22.12.0以上 | `node --version` |
| npm | Node.jsに同梱されたもの | `npm --version` |
| Git | repositoryの差分確認に使用 | `git --version` |

まず、3つをまとめて確認する。

```powershell
node --version
npm --version
git --version
```

バージョン番号がそれぞれ表示されれば次へ進める。`command not found` や「認識されていません」と表示された場合は、記事作成より先に不足しているツールを導入する。

<details>
<summary>なぜ最初にバージョンを書くのか</summary>

同じコマンドでも、メジャーバージョンやOSが違えば結果は変わる。「最新版を使う」だけでは、後から記事を読んだ人が当時の条件を再現できない。実行結果を保証した環境を数字で残しておくと、問題の切り分けが速くなる。

</details>

## 1. 下書きを作る

記事作成CLIを対話形式で起動する。

```bash
npm run new:post
```

自動化したい場合は、値を引数で渡せる。以下は `reproducible-guide` というslugで下書きを作る例だ。

```bash
npm run new:post -- --slug reproducible-guide --title "再現できる手順書" --description "実行結果まで検証できる手順書の例です。" --tags 2026,markdown
```

成功すると、原稿と画像用ディレクトリが作られる。

```text
src/content/blog/reproducible-guide.md
src/content/assets/reproducible-guide/
```

### 生成物を検証する

ファイルがあることだけでなく、Gitが新規ファイルとして認識していることも確認する。

```bash
git status --short
```

期待する表示は次のようになる。出力例はコマンドと別のブロックにし、誤って一緒にコピーされないようにする。

```text
?? src/content/assets/reproducible-guide/
?? src/content/blog/reproducible-guide.md
```

## 2. frontmatterを埋める

記事のメタデータは冒頭のfrontmatterに置く。本文ではH1を重ねず、H2から始めると、ページタイトルとの役割が重複しない。

```yaml
---
title: 再現できる手順書
slug: reproducible-guide
description: 実行結果まで検証できる手順書の例です。
publishedAt: 2026-08-27
draft: true
tags:
  - '2026'
  - markdown
---
```

`slug` とtagは小文字英数字とハイフンを使う。公開前までは `draft: true` のままにしておく。

### 画像は原稿から相対参照する

画像を `src/content/assets/` 以下へ置き、Markdownには通常の相対パスを書く。公開先のR2 URLを原稿へ直接書かないため、保存先を変えても原稿が壊れにくい。次の例は、このrepositoryに実在する画像を参照している。

```md
![Markdown記事のサンプル画像](../assets/sample-image.jpg)
```

代替テキストには「画像」ではなく、画像を見られない場合にも必要な内容を書く。

## 3. 手順と検証を対にする

操作だけを並べると、読者はどこまで成功したか判断できない。各手順を「操作 → 期待結果 → 検証」の小さな単位に分ける。

```mermaid
flowchart LR
    A[操作する] --> B[期待結果を見る]
    B --> C{検証に成功?}
    C -->|Yes| D[次の手順へ]
    C -->|No| E[状態を保存して原因を調べる]
```

このブログなら、公開前の最小検証はbuildだ。

```bash
npm run build
```

終了コードが `0` で、最後に `Complete!` が表示されればbuildは成功している。さらに、意図しない空白エラーがないかを確認する。

```bash
git diff --check
```

何も表示されなければ問題はない。コマンドの「無出力」が成功を意味する場合は、そのことを本文に明記しておく。

### 変更の要点を読む

差分全体を読む前に統計を見ると、画像の混入や想定外の大量変更に気づきやすい。

```bash
git diff --stat
```

次に本文の差分を確認する。

```bash
git diff -- src/content/blog/reproducible-guide.md
```

ファイル名を明示すると、他の作業中の差分を混ぜずに確認できる。

## 4. 危険なコマンドにガードレールを付ける

技術記事では、短さよりも事故を起こしにくいことを優先する。特に削除、上書き、deployを伴うコマンドには、対象と影響範囲を書く。

> 注意: `npm run publish` は検証だけでなく、R2・D1の同期、build、Cloudflareへのdeployまで実行する。動作確認だけなら `npm run build` を使う。

公開する準備が整ったら、frontmatterを `draft: false` に変えてから実行する。

```bash
npm run publish
```

パスワード、API token、`.env` の中身は、伏せ字であってもコピー用ブロックへ載せない。環境変数名だけを例示する。

```bash
export API_TOKEN="your-token-here"
```

上の値はプレースホルダーであり、そのままでは動かない。読者が置き換える箇所は、コマンドの直前か直後に明記する。

## 5. 失敗時の情報を残す

「失敗したらやり直す」だけでは、原因を消してしまうことがある。まず現在の状態を読み取り、ログを保存してから修正する。

```powershell
npm run build *>&1 | Tee-Object -FilePath .tmp/build.log
```

macOSやLinuxでは次のようにする。

```bash
npm run build 2>&1 | tee .tmp/build.log
```

| 症状 | 最初に確認する場所 | よくある原因 |
| --- | --- | --- |
| frontmatter error | エラーに出た記事名とfield | 必須field不足、slugの形式 |
| image not found | Markdownの相対パス | ファイル名の大文字・小文字、拡張子 |
| broken internal link | `/blog/` から始まるURL | slugの変更、末尾の余分なslash |
| deploy failure | Wranglerが返した最初のerror | login切れ、binding設定、network |

### 下書きだけを安全に取り消す

この記事の例で新規作成したファイルが不要になった場合は、削除対象を先に確認する。

```powershell
Get-Item -LiteralPath "src/content/blog/reproducible-guide.md"
Get-Item -LiteralPath "src/content/assets/reproducible-guide"
```

確認後、**自分で今作った未追跡ファイルだけ**を削除する。既存記事や、他の作業者の差分には使わない。

```powershell
Remove-Item -LiteralPath "src/content/blog/reproducible-guide.md"
Remove-Item -LiteralPath "src/content/assets/reproducible-guide" -Recurse
```

`git reset --hard` のようにrepository全体の変更を消すコマンドは、手軽な「やり直し」として記事へ載せない。

## Markdown機能の使い分け

| 表現 | 向いている用途 | 避けたい使い方 |
| --- | --- | --- |
| **太字** | 結論、判断条件 | 段落の大半を強調する |
| `inline code` | command名、file名、field名 | 長いコマンドを埋め込む |
| 箇条書き | 順不同の条件 | 手順の順番を表す |
| 番号付きリスト | 順序が必要な操作 | 順不同の特徴を並べる |
| 引用 | 注意、前提、引用 | 通常の本文すべてを囲む |
| 表 | 同じ観点での比較 | 長文をセルへ詰め込む |
| 脚注 | 本筋を止める補足 | 実行に必須の条件を隠す |

URLを単独行に置くとリンクカードになる。たとえば、このブログの構成を詳しく説明した記事は内部カードとして表示できる。

/blog/first-post

外部URLも同じ記法でカードになる。

https://zenn.dev/

文中の通常リンクにしたい場合は、[AstroのMarkdownガイド](https://docs.astro.build/en/guides/markdown-content/)のようにリンク記法を使う。

脚注は、用語の由来や補足資料のように、読まなくても手順を完了できる情報へ使う。[^source-of-truth]

[^source-of-truth]: このブログではrepository内のMarkdownと元画像を正本とし、公開環境のデータはそこから再生成できるようにしている。

## 公開前チェックリスト

- [ ] タイトルだけで読者と得られる結果が分かる
- [ ] 対象OS、version、作業ディレクトリを書いた
- [ ] コマンドへ `$` や `>` などのプロンプト記号を含めていない
- [ ] コマンドと出力例を別のコードブロックにした
- [ ] 破壊的操作の前に対象を確認する手順を書いた
- [ ] placeholderと、読者が置き換える値を説明した
- [ ] 成功条件と失敗時の確認場所を書いた
- [ ] 画像に内容の分かる代替テキストを付けた
- [ ] `npm run build` と `git diff --check` が成功した
- [ ] Raw Markdownでも構造を追える

## まとめ

Markdownの強みは、装飾を増やせることではなく、操作、結果、判断材料をプレーンテキストで残せることにある。

コマンドをコピー可能にし、前提条件、期待結果、検証、失敗時の手順まで揃えると、記事は「読んで分かった気になる説明」から「あとで再現できる資料」になる。表示結果と原稿を見比べたいときは、[このページのRaw Markdown](https://blog.kinn-kinn.com/blog/markdown-feature-showcase.md)を参照してほしい。