自社サイトをWordPressからAstroに移したとき、技術的な移行よりもずっと長引いたのが「で、誰がニュースを書くの？」という話でした。
それまで広報担当が管理画面のリッチエディタでポチポチ更新していたものが、いきなりMDXファイルになる。自分はGitもMarkdownも当たり前に触るので軽く考えていたんですが、実際に他職種のメンバーに渡してみると、想像していた3倍はつまずきました。今回はその「浸透」のために自分たちが手を入れた実装まわりの話です。
「チートシートを渡せば書ける」は幻想だった
正直なところ、最初の自分の打ち手はかなり雑でした。Markdown記法の一覧表をSlackにペタッとはってDONE、というやつです。
これが見事に滑りました。
返ってきた最初の原稿が、全部の文がベタッとつながった一段落になっていたんです。書いた本人は「ちゃんと改行したのに」と言う。原因はMarkdownでおなじみのアレでした。
これは一行目です。
ここで改行したつもり。
空行を入れると、ここで初めて段落が分かれます。WYSIWYGに慣れた人にとって「Enterを押したのに段落が分かれない」は理屈じゃなくて感覚の問題で、記法一覧を眺めても腹落ちしないんですよね。ドキュメントにはこう書いてある、で済む話じゃなかった。ここで「文字で説明してもダメだ、見せるしかない」と方針を変えました。
結局いちばん効いたのはプレビュー環境
何が一番効いたかと聞かれたら、迷わずプレビュー環境と答えます。
うちはPR単位でプレビューが立ち上がる構成にしていて、ブランチを切って原稿をpushすると https://preview.xecin.jp/pr-123/news/... みたいなURLが自動でコメントされます。これを編集者に見てもらうようにしただけで、改行問題みたいな話の9割が勝手に消えました。
理由は単純で、「自分の書いたものが本番とほぼ同じ見た目で確認できる」と、人は安心してMarkdownを書けるからです。逆に言うと、プレビューがない状態で生のテキストだけ書かせるのは、完成形が見えないまま組版しろと言っているのと同じで、そりゃ無理だよなと。
スキーマ検証も地味に効きました。フロントマターは型で縛ってあるので、title を書き忘れたり status をタイポしたりするとCIのビルドがそこで落ちます。
// src/content.config.ts（抜粋）
const news = defineCollection({
schema: z.object({
title: z.string().min(1).max(100),
summary: z.string().max(200),
publishedAt: z.coerce.date(),
status: z.enum(['draft', 'published']),
tags: z.array(z.string()).optional().default([]),
}),
});非エンジニアからすると最初は「赤いバツが出て怖い」だったんですが、慣れてくると「公開前に機械が間違いを教えてくれる」に変わっていきました。人間がレビューで「タイトル100文字超えてます」と指摘する回数が目に見えて減ったので、これは入れておいて良かった仕組みです。
3つの中でテンプレ化は、効果でいうと3番手。ただ立ち上がりの心理的ハードルは確実に下げてくれました。フロントマターの雛形をコメント付きで用意して、これをコピーして中身を差し替えてください、という渡し方にしています。
---
title: "ここにタイトル（100文字まで）"
summary: "ここに概要（200文字まで・一覧カードに出ます）"
publishedAt: 2026-06-23
status: draft
tags: ["お知らせ"]
author: "XECIN"
---
本文をここから。空行で段落を分けるのを忘れずに。画像挿入で全員が同じ地雷を踏んだ
リンクと引用は、正直すぐ覚えてもらえました。問題は画像です。
最初に編集者が書いた画像の貼り方はこうでした。プレビューでは見えていたのに、別のPRでは表示されたりされなかったりして、原因究明にけっこう時間を溶かしました。
<!-- 編集者が最初に書いた書き方。プレビューのサブパスでリンク切れする -->
うちのプレビューは /pr-123/ のようなサブパス配下にデプロイされるので、先頭スラッシュ始まりの絶対パスだと /images/... を見にいって404になる。本番（ルート直下）では偶然動くから、書いた本人もレビューする側も気づきにくいという、いちばんタチの悪いやつでした。
エンジニア側はベースURLを噛ませれば解決と分かるんですが、それを非エンジニアに毎回やってもらうのは無理がある。なので今は「画像は所定のフォルダに置いて、貼り方はこの1パターンだけ」とルールを固定し、込み入ったケースはエンジニアかAIエージェント側で吸収する形にしています。
ここは正直まだ改善の余地があって、本来はエディタ拡張なりリンターなりで「絶対パス画像を書いたら警告する」くらいまで自動化したい。今は人間の規律と目視レビューに頼っているので、仕組みで殴れていないのが心残りなんですよね。覚えてもらうのは画像・リンク・引用の3つに絞る、という割り切りで今のところ回しています。
AIがドラフト、人間がMarkdownを直す、に落ち着いた
いろいろ試した結果、今の分担はこうなりました。記事のドラフトはAIエージェントが生成してPRを出す。人間はそのMarkdownを開いて、ニュアンスや事実関係を直して整える。
この形にしてから、非エンジニアの心理的負荷がだいぶ軽くなりました。ゼロから白いMDXファイルに向き合うのと、8割できているものを直すのとでは、必要なMarkdown力が全然違うんです。空行のことを完璧に理解していなくても、すでに段落が分かれている文章を手直しするだけなら破綻しない。
スキーマ検証とプレビューが効いてくるのもここで、AIが変なフロントマターを吐けばCIで落ちるし、直した結果はプレビューで即確認できる。「AIが暴走しても型で止まる」「人の手直しはプレビューで確かめられる」という二重の安心があるから、編集者が気軽に触れる状態を保てています。
振り返って
結局のところ、非エンジニアにMarkdownを浸透させるというのは、Markdownを完璧に教え込むことではなくて、間違えても安全に気づける足場をどれだけ用意できるか、なんだろうと思っています。プレビューで見た目を、スキーマでフロントマターを、テンプレで書き出しを、それぞれ受け止める。記法そのものを暗記させる方向に頑張るより、こっちのほうがずっと効きました。
画像まわりの自動化はまだ宿題として残っているので、ここはこれからちゃんと仕組みにしていきたいところです。もっと良いやり方があったら教えてください。