内容確認を終えたMarkdown記事があっても、そのファイルを置くだけでは公開準備が整ったとはいえません。どのメタデータをCMSが読み、どのURLへ表示するのかを確かめる必要があります。問題が起きたときに戻す版も、公開前に特定しておきます。
この記事で扱うのは、slugと公開URLを変えない一記事の更新です。元ファイルから実URLまでの対応を記録し、ソースと表示結果を別々に検査します。公開する版と戻す版の両方を確認できたとき、その記事を復旧可能な状態で公開できます。
slugや公開URLを変える場合や、共通テンプレートまで触る場合は影響範囲が広がります。そのときは、Webサイト公開前後のチェックリストで変更全体の中止条件と戻し方を決めます。
Markdownだけでは記事の公開仕様は決まらない
Markdownが定めているのは、見出しやリンクなどをどのような記法で表すかです。記事の公開状態やURLまで決める共通仕様ではありません。
CommonMarkは、Markdownのブロック構文とインライン構文の解析方法を規定しています。一方で、記事冒頭に置くメタデータ領域であるfront matterは規定していません。---で囲まれた部分が常にfront matterとして読まれるわけでもありません。
front matterの形式と項目の意味は、利用するCMSやサイトジェネレーターによって変わります。Jekyllはファイル冒頭のYAML front matterを扱います。HugoはYAML以外のメタデータ形式にも対応しています。同じ draft や日付に見える項目でも、処理系が違えば公開条件まで同じとは限りません。
そのため、最初に自社サイトの入力仕様を確認します。記事を読むディレクトリを確かめます。ファイル名とslugから、どの公開URLが作られるかも確認します。
CMSが読む項目と型を確認します。未設定時の扱いと非公開になる条件まで分かれば、ソースの検査基準を作れます。
一記事の変更範囲と公開URLを先に固定する
公開作業を始める前に、今回変える一記事と、変えないものを分けます。対象が曖昧なままでは、検査が通ってもどこまで確認したのか分かりません。
対象ファイルと現在のslugを記録し、そのslugから生成される公開URLを確かめます。記事に使う画像を同時に変えるなら、そのファイルも対象に含めます。本文だけを直す場合は、テンプレートやルーティングが対象外であることを残します。
公開済み記事では、本文の都合でslugを変えません。slugがURLを決める仕組みなら、slug変更はURL変更です。
旧URLから新URLへどう移すかを先に決める必要があります。内部リンクやcanonicalも新URLへそろえ、サイトマップの更新結果まで確認します。
タイトルも自動的な変更対象にはしません。意味を明確にする軽微な修正であっても、変更前後と理由を記録します。中心となる問いまで変わるなら、同じURLの更新として進めない判断が必要です。
ソースではCMSが読む内容を検査する
Markdownファイルから判断できることと、HTMLへ変換した後にしか分からないことは別です。確認項目を一つにまとめると、構文が正しいだけで公開へ進みやすくなります。
ソースでは、CMSがfront matterを読めるかを確認します。必須項目の欠落や型の違いも検査対象です。
公開状態と日付が意図どおりかを確かめます。slugの命名と関連記事の参照先もここで見ます。画像や内部リンクは、ファイル上の書き方だけでなく参照先が存在するかまで確認します。
raw HTMLの扱いも処理系に依存します。CommonMarkはraw HTMLを構文として扱いますが、公開時に許可するか、無害化するかはレンダラー側の設計です。外部から受け取った内容を扱う場合は、使用中の処理でどのように出力されるかを確かめます。
表示結果では公開URLに出る内容を確認する
表示結果では、titleとdescriptionが想定どおりに出ているかを見ます。本文と見出しも実際の表示で確認します。画像が読み込まれ、リンクが意図したページへ進むことも必要です。
関連記事や一覧ページがfront matterを使うなら、記事詳細だけでなく、その掲載結果まで確認します。canonicalや構造化データを出力する仕組みでは、期待する公開URLと一致しているかも見ます。
AdRegionでは記事単体と公開記事群を分けて検査する
このサイトでは、記事単体の検査と、公開記事群の検査を別々に実行しています。これはMarkdownの共通仕様ではなく、AdRegionの現在の実装です。
記事単体のlintでは、front matterの存在と一部の項目を文字列として検査します。front matterの構文や型を完全に検証するものではありません。公開状態やカテゴリのほか、タイトルの表記と見出し直下の文章を確認します。
公開記事群の検査では、各記事に関連記事からの入口があるかを確認します。サイトマップに含まれる記事数も照合します。Markdownソースへnoindexが付くことも別に確かめます。
記事単体の検査を通っても、公開記事群の検査で存在しない関連記事や公開数の不一致が見つかることがあります。反対に、サイトマップへURLが入っていても、本文が読者の問いに答えている保証にはなりません。機械検査の役割を分けると、通過した検査の意味を取り違えずに済みます。
公開する版と戻す版を同時に決める
復旧できる状態とは、「履歴がどこかにあるはず」という状態ではありません。公開する版と、異常時に戻す版を識別でき、必要なファイルを実際に取り出せる状態です。
Gitを使う場合は、必要なファイルが記録されたコミットやタグなどを指定します。Gitはコミット時点のスナップショットを保存します。未追跡のファイルや、まだ記録していない変更まで自動的に保存するものではありません。
記事の画像が別の場所にあるなら、その画像も戻せるかを確かめます。外部サービス上の素材や、CMSの外にある設定は、Markdownファイルを戻すだけでは復旧しません。今回の一記事に必要なものを版管理へ含めるか、別のバックアップを対応付けます。
Gitを使わない運用でも、変更前のファイルと必要素材を取り出せるバックアップがあれば復旧元にできます。大切なのは製品名ではなく、戻す版の識別子と保管場所を公開前に確かめることです。確認できなければ、復旧可能とは記録しません。
一件の公開・復旧記録で元ファイルと公開URLを結ぶ
公開・復旧記録は、一般的な確認項目を並べるためのものではありません。今回のソースがどのHTMLとして公開され、どの版へ戻せるのかを一件ずつ対応させます。
# Markdown公開・復旧記録
対象記事:
対象ファイル:
変更しないslug:
期待する公開URL:
今回変更する範囲:
今回の対象外:
変更前の版:
公開する版:
戻す版:
戻す版を取り出せることの確認:
CMSが読むメタデータ:
ソース検査の方法と結果:
画像・リンク参照先の確認:
表示確認の場所と結果:
公開前判定: 公開可 / 保留
公開日時:
実URLで確認した結果:
公開後の判断:
復旧へ進む条件:
復旧した版:
復旧後のソース検査:
復旧後の表示確認:
復旧後の実URL確認:
最終結果:
「変更前の版」と「戻す版」は同じになることが多いものの、必ず同じとは限りません。変更前の状態に既知の問題があれば、正常と確認できた別の版を戻し先にします。その場合は、なぜその版を選んだのかも記録します。
空欄を埋めること自体が目的ではありません。戻す版を取り出せない場合や、CMSが読むメタデータを確認できない場合は、公開前判定を保留にします。確認方法がない項目を「問題なし」で済ませないための記録です。
実URLでソースどおりに表示されたか確かめる
プレビューが正しくても、本番の実URLが同じ結果になるとは限りません。公開後は、対象ファイルに対応するURLを直接開きます。
最初に、ページが正常な内容を伴う応答を返しているかを見ます。Google検索の技術要件でも、ページが正常に動作し、インデックス登録可能な内容を持つことが前提とされています。ただし、条件を満たしたからといってインデックス登録が保証されるわけではありません。
次に、titleとdescriptionをプレビューと照合します。本文が同じ内容かを確認し、画像とリンクも実際に操作します。宣言したcanonicalは、期待する公開URLと比べます。
canonicalは検索エンジンへの強いシグナルですが、命令ではありません。Googleのcanonicalに関する説明でも、最終的に別のURLが選ばれる場合があると示されています。ここで確認するのは、サイト側の宣言が設計どおりかどうかです。
一覧や関連記事に出る設計なら、その入口から同じ記事へ移動できるかも確かめます。異常が見つかった場合に修正を続けるか復旧するかは、公開チェックシートの条件に従います。判断結果と対象となった版を公開・復旧記録へ戻します。
復旧後も同じ実URLをもう一度確認する
戻す版を配置しただけでは、復旧は終わりません。ソース、表示結果、実URLの順にもう一度確かめます。
最初に、復旧したファイルへソース検査を実行します。次に、レンダリングした表示を確認します。最後に同じ実URLを開き、正常な内容へ戻ったことを確かめます。キャッシュや生成物が残る仕組みでは、元ファイルだけが戻り、公開ページは変わっていない場合があります。
同じURLへ内容を戻しても、検索結果の表示まで直ちに元へ戻るとは限りません。検索エンジンによる再取得や処理は別に進みます。復旧完了は、まず自社が管理できるソースと公開ページの対応で判断します。
内容確認を終えた記事を一つ選び、対象ファイルと変えないslugを記録してください。期待する公開URLと戻す版まで特定できれば、ソース検査へ進めます。戻す版を取り出せるか確認できない間は、公開を保留します。