Pixels to Motors DAY 193
公開基盤構築 Build-in-public 二層公開システム

記事をビジュアルウィジェットで作り直す日 ── STUDIO と GitHub Pages の二層公開システムを建てた

FROM / 開始時
「md を HTML にしたい」
md → HTML テンプレ量産 散文 + 部分図解
→
TO / 到達点
二層公開システムの完成
全要素図解化 STUDIO + GH Pages 3操作で公開
💡 Key Takeaway ── 本日の達成
01 / 視覚化原則
全テキスト段落を廃止
18の視覚コンポーネントで構成。散文ゼロ、「読む」から「触る」への体験転換を設計
02 / 公開基盤
STUDIO + GitHub Pages 二層
役割の違う2層がバナーとロゴで相互リンク。同じ情報を別体験として2回提供
03 / 運用設計
記事追加は3操作で完結
Claude Project で自動生成、articles.json で動的描画。index.html は触らない
01 起点

「mdをHTML化したい」── 意図と提案のすれ違い

提案 / 最初の回答 廃案
  • ツール構成markdown-it + highlight.js + 自前CSS
  • 変換系統node convert.js で md → 綺麗な HTML ページ
  • 想定する出力h2 から自動目次、Key Takeaway をコールアウト
  • 評価技術的には正しい、意図とズレていた
意図 / 本当に欲しかったもの 本筋 ★
  • 基準点DAY192_two_cameras_role.html(既存の埋込ウィジェット)
  • 拡張方向記事1本まるごとを同じフォーマットで作る
  • 想定する出力記事内容に合わせて図解を生成する自動化
  • 気づき1往復で食い違いを発見、方針転換
02 転換 01

テンプレ方式の廃案 ── 順序を反転させる

"
記事に合わせて図解を作るから、
テンプレ方式の必要はないね。
Day 193
方針転換
テンプレ方式 / パターン化 廃案
  • 順序テンプレを先に作る → 論点をはめ込む
  • 候補タブ切替 / 二項対比 / フロー型 の3種
  • トレードオフブランドは揃うが、毎回の論点が痩せる
  • 構造固定 → 内容が形に合わせて変形
都度生成 / 内容駆動 採用 ★
  • 順序記事の論点を見る → 図解の形を作る
  • 担保白黒3色 + 1.5pxボーダー + 2書体だけ固定
  • トレードオフブランドは揺れ得るが、論点は活きる
  • 構造自由 → 形は内容に合わせて変形
担保する3つの最小ルール

ブランド一貫性はここだけで守る

RULE 01 / カラー
3色のみ・白黒反転
アクセント色禁止、強調は背景反転
RULE 02 / 線
1.5px ソリッド
破線は警告枠のみ、装飾線は不使用
RULE 03 / 書体
Plex Mono + Noto Sans JP
見出しMono、本文Sans、混在は禁則
03 転換 02

「全部図解で作って」── 散文段落の完全廃止

"
なんかメリット感じないね。
全部図解で作ってみて。
Day 193
全廃指示
廃止された段落と変換先

「読む文章」をすべて視覚要素に置き換える

削除 01
section-lead
各セクションの導入文 → 完全廃止。タイトルだけで足りる
変換 02
widget-note
図解下の補足 → tag-set または value-row
変換 03
quote-card
引用文 → keyphrase-block(大フレーズ + ソース)
変換 04
decision-card
採用仕様 → spec-block(アイコン + キー + 値の4分割)
変換 05
warning-card
警告文 → concern-card(stats + actionタグ)
変換 06
closing-statement
締めの一文 → before-after(左右対比 + チェック項目)
最初のビジュアル化版
49
KB / 散文 + 図解混在
DISCARDED
変換後の構成要素
18
視覚コンポーネント
FINAL
残った散文段落
0
本文中の p タグ
TARGET
04 選択

STUDIO と GitHub Pages ── 役割の違う2層を共存させる

STUDIO / 通常版 読む層
  • HTML/CSS/JS制限的、Embedのiframeのみ
  • 編集Cmd+V で md を貼るだけ
  • サイト統合adaptdesign.jp 配下
  • コスト有料プラン込み
GitHub Pages / インタラクティブ版 触る層
  • HTML/CSS/JS完全自由、JS がそのまま動く
  • 編集git push (Web UI でも可)
  • サイト統合別 URL、相互リンクで接続
  • コスト無料 (Public リポジトリ)
3つの選択肢から1つ

公開先の構造をどう選ぶか

A
GH Pages 全寄せ
B
iframe 埋込
C
ウィジェット部分埋込
↑案を選択してください
案A ── 全部 GitHub Pages に置く + STUDIO から誘導 採用 ★
仕組み
役割分担
STUDIO=読む / GH Pages=触る
URL
別ドメイン
pixelstomotors.github.io/interactive-articles/
接続
バナーとロゴで往復
STUDIO上部にCTA、各記事上部にDAYタグでSTUDIO戻り
JSがそのまま動く 無料 役割が明確
案B ── STUDIO記事内に iframe で GH Pages 版を埋込 不採用
仕組み
中身を委譲
URLはadaptdesign.jp、表示中身はGH Pagesから
課題
高さ調整が必要
レスポンシブで工夫が要る
体験
「読む」と「触る」が混在
体験の役割分担が曖昧になる
URLは一貫 役割の境界がぼやける
案C ── 図解ウィジェットだけを部分埋込(従来通り) 現状維持
仕組み
これまでと同じ
本文はSTUDIO、図解は要所でEmbed
利点
運用変更なし
新しい層を建てる必要がない
欠点
記事全体の図解化は不可
「触る記事」という体験は得られない
変化なし 体験拡張なし
"
役割が違うコンテンツとして共存させる。
STUDIO は「読む」、インタラクティブ版は「触る」。
Day 193
二層構造決定
05 生成

Claude Project でシステム化 ── 同じ品質で量産する仕組み

確定構成 Pixels to Motors Visual Article Builder
⚙
カスタム指示
PROJECT_
INSTRUCTIONS.md
▤
ナレッジ 01
TEMPLATE.html
34 KB
▦
ナレッジ 02
COMPONENTS.md
16 KB
↳
入力
DAY{N}_
article.md
定義済みコンポーネント
18
種類 / 視覚部品
CATALOG
記事生成までの手順
1
md添付 → HTML出力
FLOW
記事公開までの時間
3-5
分 / 1記事あたり
TARGET
!
運用上の落とし穴
原則が抜けると散文段落が混入する
原因
コピペ漏れ
影響
品質ブレ
対策
指示文に集約
→ 試行錯誤で固まったルールは PROJECT_INSTRUCTIONS.md に一元化する
06 接続

バナーで二層を往復させる ── STUDIO 上部に置く CTA

確定仕様 P2M_Interactive_Banner
⟷
サイズ
720 × 160
max-width
◼
カラー
#0d0d0d
+ #f5f5f0
▤
構成
アイコン +
2行 + CTA
◎
ホバー
グレー化
動きなし
BEFORE / 初版
↑ ⇄ →
3種の動的アニメーション
浮き上がり2px
白黒反転CTA
矢印スライド→ →
→
AFTER / 最終版
◯ ─ ◯
グレー化のみ・動きなし
浮き上がり✕ 廃止
白黒反転✕ 廃止
ホバー◎ 背景のみ
設置箇所

STUDIO 記事への組込み手順

STUDIO 編集画面 「埋め込み」ブロック HTML全体をコピペ href を新URLに書換 記事1本につき1か所のみ
07 インフラ

GitHub Pages 公開構造 ── URL と分離設計

PixelsToMotors/interactive-articles (Public)

リポジトリの3要素

FILE 01 / 触らない
index.html
記事一覧。JS で articles.json を fetch して動的描画。初回作成後は編集不要
FILE 02 / 毎回編集
articles.json
記事メタデータ。新記事追加時に配列先頭に1ブロック追記するだけ
DIR 03 / 毎回追加
{slug}/index.html
記事ごとのフォルダ + 中に index.html。Visual Article Builder の出力を配置
資産の分離理由

なぜ Public リポジトリを切り出したか

PRIVATE / 既存
r2r2r-content
記事資産 (md / 図解原稿)。Free plan で Pages は使えない
PUBLIC / 新設
interactive-articles
公開HTMLのみ。Pages 有効、原稿と公開物を分離
Settings → Pages

GitHub Pages 有効化フロー

  1. 01
    リポジトリ Settings → Pages を開く +
    SETUP Public リポジトリのみ可
  2. 02
    Source: Deploy from a branch を選択 +
    SOURCE Actions ではなく branch 配信
  3. 03
    Branch: main / (root) を選択 +
    BRANCH サブディレクトリ不要
  4. 04
    Save → 1〜2分待つ +
    WAIT 初回ビルドのみ若干かかる
  5. 05
    https://pixelstomotors.github.io/interactive-articles/ で公開 +
    LIVE 記事URL: /{slug}/ STUDIO と slug を揃える
08 運用

articles.json で動的化 ── 3記事目で破綻しない設計

初版 / 直書き構成 廃案
  • 構造index.html に記事カードを HTML 直書き
  • 追加記事ごとに index.html を編集
  • 限界3記事目で疲れる、100記事目では破綻
  • 負債初期の運用設計が10ヶ月後に効いてくる
最終 / JSON 分離 + JS 動的描画 採用 ★
  • 構造articles.json + index.html (fetch で読込)
  • 追加JSON 配列の先頭に1ブロック追記のみ
  • 挙動day 降順で自動ソート、件数カウンタも自動
  • 永続性100記事目でも持つ運用構造
記事1本追加の手順

最終的に固まった3操作運用

  1. 01
    新フォルダ + index.html を Upload +
    GITHUB Add file → Upload files フォルダ名 = slug
  2. 02
    articles.json に1ブロック追記 +
    JSON 鉛筆アイコンで編集 配列の先頭に追加
  3. 03
    STUDIO 記事に P2M_Interactive_Banner を埋込 +
    STUDIO 「埋め込み」ブロック href を新 URL に書換
公開までの操作数
3
アクション / 1記事
OPS
md 投稿から公開まで
3-5
分 / 想定
TIME
index.html の編集
0
回 / 記事追加時
UNTOUCHED
09 反省

このセッションが示したこと ── 二つの転換点

設計の意思決定

非典型なデザインシステムの選択

転換 01 / 順序の反転
テンプレ → 都度生成
部品は最小限、原則は固定、構造は自由。固定テンプレに論点をはめるのではなく、論点を見てから図解の形を作る
転換 02 / 役割の分離
混在 → 二層分担
STUDIO 版とインタラクティブ版で「読む」と「触る」を分けた。同じ情報を別の体験として2回提供する設計
!
Build-in-public 長期運用の教訓
初期の運用設計は10ヶ月後の負債になる
破綻ライン
3 記事
耐用
100 記事+
差を分けるもの
初期動的化
→ 早めに JSON 分離 + JS 動的描画にしておくと、未来の自分が助かる
本日の結論 ── 「読む」と「触る」を二層で同居させた日
BEFORE
STUDIO 単層・散文中心の公開層
STUDIO で md を公開○
図解は記事内に部分埋込○
全要素を図解化した記事✕
記事追加の自動化✕
「触る記事」という体験✕
→
AFTER
STUDIO + GitHub Pages の二層公開システム
STUDIO 版 (読む)◎
インタラクティブ版 (触る)◎
バナーとロゴで相互リンク◎
3操作で公開完結◎
articles.json で動的化◎