共通している部分

変わった部分

Quarto 版の強み

1. コード実行ができる（最大の違い）

Astro 版では記事は「純粋な Markdown」だけでした。Quarto 版は：

import matplotlib.pyplot as plt
plt.plot([1, 3, 2, 5])
plt.show()

のように、実行結果つきの図を記事に埋め込めます。データ分析ブログや教材には圧倒的に有利です。

Quarto 版の注意点

どちらを選ぶか

まとめ

• 設計思想（GitHub を CMS にする）はそのまま、生成エンジンを Astro → Quarto に置き換え
• コード実行・検索・SEO の標準装備が Quarto 版の強み
• 型安全や UI の自由度は Astro 版が上。目的に応じて選ぶのが良い

両者の立ち位置がそもそも違う

つまり 「Web アプリを作るための道具」vs「文章と計算をまとめる道具」という違いが根底にあります。

言語・エコシステム

レンダリングモデル

コード実行（最大の差）

import matplotlib.pyplot as plt
labels = ["Astro", "Quarto"]
times = [1, 5]
plt.bar(labels, times)
plt.ylabel("コード実行コスト（相対）")
plt.show()

/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 12467 (\N{KATAKANA LETTER KO}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 12540 (\N{KATAKANA-HIRAGANA PROLONGED SOUND MARK}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 12489 (\N{KATAKANA LETTER DO}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 23455 (\N{CJK UNIFIED IDEOGRAPH-5B9F}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 34892 (\N{CJK UNIFIED IDEOGRAPH-884C}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 12473 (\N{KATAKANA LETTER SU}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 12488 (\N{KATAKANA LETTER TO}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 65288 (\N{FULLWIDTH LEFT PARENTHESIS}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 30456 (\N{CJK UNIFIED IDEOGRAPH-76F8}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 23550 (\N{CJK UNIFIED IDEOGRAPH-5BFE}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)
/opt/hostedtoolcache/Python/3.12.13/x64/lib/python3.12/site-packages/IPython/core/pylabtools.py:158: UserWarning: Glyph 65289 (\N{FULLWIDTH RIGHT PARENTHESIS}) missing from font(s) DejaVu Sans.
  fig.canvas.print_figure(bytes_io, **kw)

出力形式

デプロイ・運用

どちらを選ぶか（使い分け）

• Web アプリ寄りのサイト（ログイン・フォーム・SPA 的な体験）→ Astro
• データ分析・コード付き記事、論文、レポート → Quarto
• ブログだけで、とにかく軽く速く → どちらでも。Astro は型安全、Quarto は検索・多形式がお得
• GitHub Issues/Discussions を CMS にしたい → 両対応できるが、コードを記事に載せたいなら Quarto が有利

まとめ

• 技術スタックで見ると 「JS の Web フレームワーク」と「計算対応の文書エンジン」は住み分けが明確
• この CMS は「執筆 + コード実行 + 多形式」を活かして Quarto 側を採用
• どちらか一方が「正解」ではなく、作るものの性質で選ぶのが正しい

4つの役割

データの流れ

1. 記事を書く（Issue / Discussion）
2. status:published ラベルを付ける
3. GitHub Actions が自動で起動
   ├─ Node.js が GitHub API から記事本文を取得
   ├─ frontmatter を Quarto 用に変換して posts/{slug}/index.qmd を作成
   └─ quarto render で _site/ を生成
4. _site/ が GitHub Pages にデプロイ

なぜ「Issue を書く」だけでブログになるのか

Issue / Discussion には次の便利な機能があります。

• ラベルで公開/非公開を制御できる
• 編集履歴が残る（GitHub 上で全文の差分が見られる）
• コメントで読者とやり取りできる
• 通知や GitHub App 連携が使える

つまり「専用の管理画面」を作らなくても、GitHub が管理画面の役割を果たしてくれます。

変換処理のポイント

GitHub の Issue 本文は次のように書きます（これが記事の「原稿」です）。

---
slug: my-first-post
title: My First Post
publishedAt: 2026-08-02
tags: [quarto, cms]
category: blog
---

# 本文

ここに Markdown で書く。

この frontmatter は Node.js スクリプトが読み取り、Quarto 用のフィールド（date / categories / description）に変換して .qmd を生成します。

このサイトを動かすファイル

まとめ

• 「原稿 = Issue」「変換 = Actions」「生成 = Quarto」「公開 = Pages」
• 専用サーバー不要・無料・GitHub 内で完結
• 記事の公開は「ラベルを付けるだけ」という手軽さが最大の利点

1. frontmatter（原稿の先頭の --- ブロック）

---
slug: my-first-post
title: My First Post
publishedAt: 2026-08-02
tags: [quarto, cms]
excerpt: 一覧に表示する短い説明（任意）
category: blog
---

title: "チュートリアル: 公開手順"   # OK
title: チュートリアル: 公開手順      # NG（YAML 解析エラー）

2. 本文（Markdown）

--- の後ろに Markdown を書きます。

# 見出し

**強調** や *斜体*、[リンク](https://example.com) が使えます。

- 箇条書き
- 箇条書き

## コードブロック

```python
print("Hello")

## 3. コードを実行する（Quarto の強み）

`python` や `r` を波括弧で囲むと、**ビルド時に実行**されます。

````markdown

::: {#35317d34 .cell execution_count=1}
``` {.python .cell-code}
import matplotlib.pyplot as plt
plt.plot([1, 2, 3], [4, 5, 1])
plt.show()

:::

````

• python（波括弧なし）: 表示のみ（実行しない）
• {python}: 実行して結果を埋め込む

4. 画像について

画像は本文に ドラッグ & ドロップ で貼ってください。GitHub が自動で URL に変換し、そのまま記事に表示されます。

![説明](https://user-images.githubusercontent.com/...)

5. 公開までの流れ

1. 「New Issue」から Blog Post テンプレートを選択
2. frontmatter と本文を編集して作成
3. ラベルに status:published を追加
4. GitHub Actions が自動ビルド → サイトに反映（数分）

まとめ

• 原稿は「frontmatter + Markdown」
• slug が重複しないように、publishedAt を正しく書くのが最低限のルール
• あとは GitHub の Markdown をそのまま書けば OK

marimo とは

marimo は、Python コードをセル単位で実行し、変数の依存関係を自動追跡するオープンソースのノートブックです。

• セルを動かすと、依存しているセルだけ自動で再実行
• 通常の .ipynb（Jupyter）と違い、実行順の不整合が起きにくい
• GitHub 上でも差分が見やすい .py 形式で保存できる

なぜ Quarto と相性がいいのか

Quarto は marimo ノートブックをそのままレンダリングできます。

つまり「marimo で試行錯誤してから、Quarto の記事に展開する」という流れが自然です。

使ってみる（手元の環境）

このリポジトリの requirements.txt には marimo が含まれているので、npm run generate の前に依存を入れれば使えます。

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
marimo edit notebook.py

macOS でシステム Python に直接入れると PEP 668 の制限に当たるので、必ず venv（仮想環境）を使いましょう。

記事への展開例

marimo で書いたロジックを記事に載せる場合、2つの選択肢があります。

A. .qmd に Python ブロックとして書く（推奨）

import matplotlib.pyplot as plt

x = range(1, 11)
y = [v * 2 for v in x]
plt.bar(x, y)
plt.show()

注意点

• marimo は インタラクティブな作業用のツールです。公開サイトのビルド（CI）では marimo 自体の実行は行いません（コードは .qmd の Python ブロックとして実行されます）
• marimo で試したコードは、記事に載せるときは「実行結果が再現できる」形（seed 固定等）にするのがベター

まとめ

• marimo = 依存関係を自動追跡する Python ノートブック
• この CMS の環境に同梱されており、marimo edit で作業可能
• 試行錯誤は marimo、公開は Quarto（.qmd）という役割分担がおすすめ

この CMS の構成（共通の骨格）

Issue / Discussion を書く
  → 公開ラベルの記事を取得して Markdown(.md / .qmd) を生成
  → 静的サイトジェネレーターで HTML 化
  → GitHub Pages にデプロイ

この骨格はどのツールでも同じです。変わるのは「変換先のファイル形式」と「レンダリングエンジン」だけです。

静的サイトジェネレーター系

文書・計算系

Quarto と比べた評価軸

なぜこの CMS は Quarto なのか

この CMS（issues-quarto-cms）が Quarto を選んだ理由：

1. コード実行 + 結果埋め込みが記事になる（本サイトの記事がそのまま実例）
2. 検索・sitemap・RSS が設定だけで動く
3. 多形式出力への拡張余地（同じ原稿を PDF にできる）
4. GitHub Actions + quarto render が公式の設定アクションで簡単に組み込める

逆に「別のツールのほうが良い」ケース

まとめ

• 「Issue を CMS にする」骨格は どのツールでも流用可能
• 選定の決め手は コード実行・出力形式・ビルド速度 のどれを優先するか
• この CMS は「コード付き記事 + 多形式 + 手軽さ」で Quarto を採用
• 目的が変わったら、scripts/ の出力先とレンダラーを差し替えるだけで他のツールに移行できます

使うラベル

新規 Issue はテンプレートにより status:draft で作成されます。公開したくなったらラベルを status:published に変更するだけです。

切り替え方

何が起きるのか

ラベルを変更すると GitHub Actions が自動で再ビルドします。

• 公開にした記事 → posts/{slug}/index.qmd が生成され、サイトに表示
• 非公開にした記事 → 次回ビルドで一覧から消える

つまり「ラベルを変える = サイトの内容を変える」という体験です。

実際の動作（技術的な補足）

ビルドスクリプトは GitHub API で label:"status:published" の記事だけを取得します。

const q = `repo:${REPO} label:"status:published" is:issue`;

status:published が付いていない記事はそもそも取得されないため、下書きが誤って公開されることはありません。

その他のトリガー

再ビルドが走るのはラベル変更だけではありません。

まとめ

• 公開/非公開は status:published / status:draft ラベルで制御
• 新規記事は自動で「下書き」スタートなので安心
• ラベルを変えるだけで、数分後にサイトへ反映される

何が嬉しいのか

普通のブログでは「コードを書いて、自分で実行して、スクリーンショットを貼って、その結果の説明を書く」という手順が必要です。Quarto なら：

• コードがそのまま記事になる（コピペの手間なし）
• 結果が常に最新（コードが変われば自動で再計算）
• 図は自動生成（画像アップロード不要）
• 再現性がある（読者も同じコードを実行して検証できる）

具体的な例：Python

下のコードブロックは、この記事をビルドするときに Quarto が実際に実行しています。

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 4 * np.pi, 200)
plt.plot(x, np.sin(x), label="sin(x)")
plt.xlabel("x")
plt.ylabel("y")
plt.legend()
plt.show()

この記事が表示されているなら、上の図は「実行された結果」です。画像を1枚もアップロードしていません。

コードを非表示にする

「コードは見せたくない、結果だけ見せたい」場合は #| echo: false を付けるだけです。

この行は HTML に表示されません: 77

対応言語

• R（統計解析・データサイエンスの本場）
• Python（機械学習・Web 系）
• Julia（科学計算）
• Observable JS（インタラクティブな可視化）

この CMS での注意

• Python コードはこの CMS のビルド環境に既定で有効です（requirements.txt で依存を管理）
• R を使いたい場合は .github/workflows/build.yml の ENABLE_R を true に変更
• コードを書かない記事には影響ありません（ビルド時間もほぼ変わりません）

まとめ

Quarto は「説明と実行結果を1つの原稿で管理」できるため、データ分析ブログ・技術記事・教材に強みを発揮します。この CMS と組み合わせれば、Issue にコードを書くだけで「実行済みの図付き記事」が公開されます。

出力できる形式

なぜ便利なのか

この CMS との関係

この CMS は「ブログ（HTML）」に特化していますが、Quarto 本来の柔軟性の上に成り立っています。将来的には：

• 記事を PDF に書き出して保存版にする
• 特定の章だけスライド化して勉強会で使う

といった使い方にも発展できます。

まとめ

• Quarto は「HTML 専用」ではなく、多形式対応の文書エンジン
• 内容と見た目が分離されているため、メンテナンスが楽
• この CMS では HTML（ブログ）として活用中。必要に応じて PDF 等にも展開可能

コードブロック単位のオプション（#| コメント）

コードブロックの先頭に #| で始まる YAML 風コメントを書くと、そのブロックだけ挙動を変えられます。

1〜100 の合計 = 5050

プロジェクト単位の設定（_quarto.yml）

この CMS では次のように設定しています。

execute:
  freeze: auto
  execute-dir: project

• freeze: auto: 原稿（.qmd）が変わっていなければ、前回の計算結果（_freeze/）を再利用する
• execute-dir: project: 実行時の作業ディレクトリをプロジェクト直下に統一（ファイルパスの混乱を防ぐ）

freeze と cache の違い

つまり 「変わっていない記事は再計算しない」ことで、CMS で記事を追加したときのビルド時間を抑えています。

再現性のポイント

1. コードに乱数を使うときは seed を固定する
2. 依存バージョンは requirements.txt 等で固定する
3. 外部データは URL を明記する（コードでダウンロード）

import numpy as np

np.random.seed(42)
print("固定 seed なら毎回同じ結果:", np.random.randint(0, 100, 3))

固定 seed なら毎回同じ結果: [51 92 14]

まとめ

• #| オプションで「実行する/しない」「表示する/しない」を細かく制御
• freeze: auto が「変わらない記事の再計算」を省略してビルドを高速化
• コード実行は「再現性」と「自動化」の両方を手に入れるための機能

何ができるのか

なぜ Markdown なのか

Markdown はプレーンテキストなので次の利点があります。

1. バージョン管理がしやすい（Git の差分が見やすい）
2. どこでも編集できる（エディタ / GitHub の Web UI / スマホのアプリ）
3. 変換が速い・依存が少ない

この CMS での位置づけ

このサイト（issues-quarto-cms）では、Quarto を「記事のレンダリングエンジン」として使っています。

• 記事の原稿は GitHub の Issue / Discussion（Markdown）
• GitHub Actions が原稿を posts/{slug}/index.qmd に変換
• quarto render が一覧・個別ページ・検索・サイトマップまで自動生成

つまり 「書く場所」は GitHub、「見た目」は Quarto、という分担です。

まとめ

• Quarto = Markdown から多様な形式を作れる文書ツール
• 特に R / Python コードを実行して結果を埋め込めるのが最大の強み
• この CMS では記事の公開エンジンとして活用しています

次の記事では、この「コード実行」のメリットを具体的に解説します。

1. データの読み込み

GitHub の公開データセットを直接読み込みます（#| echo: false でコードを非表示にしています）。

行数: 244

2. 要約統計量

データの概要をそのまま表示します。

df.describe()

3. 可視化

グラフも実行結果として自動埋め込みされます。

import seaborn as sns

sns.histplot(df["tip"], kde=True)

4. 条件ごとの集計

df.groupby("day")["tip"].mean().round(2)

day
Fri     2.73
Sat     2.99
Sun     3.26
Thur    2.77
Name: tip, dtype: float64

何が起きているのか

上のコードは この記事がビルドされるときに実行され、表やグラフが HTML に埋め込まれます。

• 元データが更新されれば、記事を再ビルドするだけで結果も更新
• 「コード」と「結果」が常に一致するため、誤ったスクリーンショット貼り間違いが起きない
• 読者に「コードと結果の両方」を見せられるので、再現性も高い

コードを載せたくない部分の扱い

「実行はするけどコードは表示しない」部分は #| echo: false、逆に「コードは見せるが実行しない」部分は #| eval: false と使い分けます。

まとめ

• 読み込み → 集計 → 可視化まで、コードブロックだけで完結
• 結果は常に最新で、画像アップロード不要
• #| echo / #| eval を組み合わせて「見せ方」を調整

Issue にこのままコードを書けば、この CMS でも同じ動きをします。

このサイトで動いている機能

listing の設定例（このサイトのホーム）

---
title: "Quarto Issues CMS"
listing:
  contents: posts
  sort: "date desc"
  type: grid
  filter-ui: true
  categories: true
  feed: true   # index.xml を自動生成
---

• contents: posts → posts/ 配下の記事を自動収集
• sort: "date desc" → 新しい順
• filter-ui: true + categories: true → カテゴリで絞り込み

検索はどう動く？

quarto render すると search.json が生成され、記事本文の全文が検索対象になります。追加のサービス（Algolia 等）は不要です。

テーマで見た目を変更

_quarto.yml の format.html.theme を変えるだけで、全体の配色が変わります。

format:
  html:
    theme: cosmo   # bootswatch のテーマ名（cosmo, flatly, journal ...）
    css: styles.css

この CMS はさらに styles.css で neo brutalism 風のカスタムスタイル（太いボーダー・強いシャドウ）を適用しています。

まとめ

• ブログに必要な「一覧・検索・SEO・共有」が Quarto 標準機能
• 見た目はテーマ + CSS で柔軟にカスタマイズ可能
• この CMS はそれらをほぼ「設定だけで」利用しています

① slug は必ずユニークに

slug が重複すると、後から処理される方の記事が スキップ（無視）されます。特に：

• Issue と Discussion の間でも重複 NG
• コピーして新規記事を作る際に slug の変更を忘れがち

slug: my-first-post   # 使い回さない
slug: my-second-post  # 一意に

② YAML のコロン（:）に注意

値の中に :（コロン＋スペース）を含むと YAML 解析エラーになります。

title: "Tutorial: 公開手順"   # OK（引用符で囲む）
title: Tutorial: 公開手順      # NG

title だけでなく excerpt も同様に注意してください。

③ 画像は「GitHub が発行する URL」のまま表示

この CMS は画像をローカルに保存せず、Issue に貼った画像の URL をそのまま使います。

• 長所: 仕組みがシンプル・ GitHub 仕様の変化に強い
• 短所: GitHub が画像を保持している間だけ有効（外部の Issue 等を消すと表示が切れる）

運用上は「画像を貼り直したら URL が変わる → 記事も更新が必要」という点だけ覚えておいてください。

④ コードを実行するとビルドが遅くなる

{python} や {r} のブロックは毎回（変更時は）実行されます。

• 重い計算・大きいデータは #| cache: true や freeze: auto でキャッシュ
• どうしても重い処理は「結果の図を画像で貼る」に切り替える手もある
• コードを含まない記事はビルド時間にほとんど影響なし

⑤ 反映まで数分かかる / 定期ビルドは遅延する

• GitHub Pages への反映は Actions 完了まで数分かかります
• 15分ごとの定期ビルドは GitHub 側の状況で遅延することがあります
• すぐ反映したいときは、Issue 編集 or ラベル変更、または Actions タブの workflow_dispatch（手動実行）を利用

⑥ Discussions を使うには事前設定が必要

Discussion を原稿に使う場合：

• リポジトリの Settings > Features > Discussions を有効化する
• 投稿用のカテゴリ（例: blog）を用意する
• Issue 版だけであれば設定不要

⑦ コード実行環境（Python / R）

• Python: この CMS ではデフォルト有効。requirements.txt（jupyter, numpy, pandas, matplotlib, seaborn, marimo）をビルド時にインストール
• R: 既定ではオフ。使いたい場合は .github/workflows/build.yml の ENABLE_R を true に変更
• 使いたいパッケージが増えたら requirements.txt に追記

⑧ category は1つ

category は1つだけ書けます（配列ではなく単一の値）。複数カテゴリで整理したい場合は tags を使いましょう。

まとめ

• 最低限守るのは slug の一意性と YAML の引用符
• 画像・ビルド時間・反映遅延は仕組み上の特性として理解しておく
• 細かいところは DEV-MEMO.md にもまとめてあります