コピペで試せるMarkdown記事の実践テンプレート

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

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

元の記法を確認したい場合は、この記事のRaw Markdownを開く。このサイトでは、公開記事のURL末尾に .md を付けると、frontmatterを含む原稿をプレーンテキストで読める。

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

先に結論

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

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

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

0. 前提条件を固定する

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

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

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

node --version
npm --version
git --version

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

なぜ最初にバージョンを書くのか

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

1. 下書きを作る

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

npm run new:post

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

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

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

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

生成物を検証する

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

git status --short

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

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

2. frontmatterを埋める

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

---
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に実在する画像を参照している。

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

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

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

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

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

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

npm run build

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

git diff --check

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

変更の要点を読む

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

git diff --stat

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

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

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

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

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

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

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

npm run publish

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

export API_TOKEN="your-token-here"

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

5. 失敗時の情報を残す

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

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

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

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

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

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

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

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

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名	長いコマンドを埋め込む
箇条書き	順不同の条件	手順の順番を表す
番号付きリスト	順序が必要な操作	順不同の特徴を並べる
引用	注意、前提、引用	通常の本文すべてを囲む
表	同じ観点での比較	長文をセルへ詰め込む
脚注	本筋を止める補足	実行に必須の条件を隠す