From abb67a607d1663a8725e895e696602fceafca44e Mon Sep 17 00:00:00 2001
From: spuithori <biz@spuit.tech>
Date: Thu, 8 Oct 2026 00:54:34 +0900
Subject: [PATCH] add.

---
 04-minisites.md  |  47 +++++++++
 08-site-embed.md | 241 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 288 insertions(+)
 create mode 100644 08-site-embed.md

diff --git a/04-minisites.md b/04-minisites.md
index dc563de..2a64fec 100644
--- a/04-minisites.md
+++ b/04-minisites.md
@@ -63,6 +63,53 @@
 
 ミニサイトの管理画面から、公開済みの記事を追加することもできます。
 
+## サイト内カテゴリーで記事を分類する
+
+ミニサイトの中だけで使うカテゴリーを作れます。
+たとえば会社のお知らせ用のミニサイトなら、「お知らせ」「プレスリリース」「IR」のように分けられます。
+
+ミニサイトにカテゴリーがあると、ミニサイトのトップページの記事一覧の上にカテゴリーのナビが表示され、読者がカテゴリーごとに記事を絞り込めます。記事のページにも、その記事のカテゴリーが表示されます。
+
+<!-- スクリーンショット: カテゴリーのナビが表示されたミニサイト -->
+
+> サイト内カテゴリーは、エディタの「カテゴリー・お題」で選ぶ mochott 全体のカテゴリーとは別のものです。両方を設定することもできます。
+
+### カテゴリーを作る
+
+カテゴリーを作る方法は2つあります。
+
+- **記事を書きながら作る**: エディタでミニサイトを選ぶと、その下に「（ミニサイト名）のカテゴリー」の欄が出ます。名前を入力して、一覧にない場合は「『（名前）』を作成」を選ぶと、その場で作られます。ミニサイトの記事管理の画面でも、同じように作れます
+- **まとめて作る**: ミニサイトの設定画面の「サイト内カテゴリー」で、追加・名前の変更・並べ替え・削除ができます
+
+カテゴリーは、ひとつのミニサイトに20個まで作れます。名前は50文字までです。
+
+### カテゴリーの ID について
+
+カテゴリーには、URL に使われる ID があります（例: `press`）。カテゴリーで絞り込んだページは `?category=press` のような URL になります。
+
+- 記事を書きながら作った場合、ID は自動で決まります。名前が英数字ならその名前から（「Press Release」なら `press-release`）、日本語などの名前なら `c1`、`c2` … になります
+- ミニサイトの設定画面で作る場合は、ID を自分で指定できます（半角の小文字・数字・ハイフンで32文字まで）
+- ID は、一度保存すると変更できません。URL を変えないためです。意味のある ID にしたい場合は、設定画面から作ってください
+
+### 記事にカテゴリーを付ける
+
+- エディタで記事を書くとき、ミニサイトの下の欄でカテゴリーを選びます
+- 公開済みの記事は、ミニサイトの記事管理の画面で、記事ごとにカテゴリーを変えられます
+
+### 知っておきたいこと
+
+- 記事が1件もないカテゴリーは、読者向けのナビには表示されません
+- カテゴリーを削除すると、そのカテゴリーの記事は「未分類」になります。記事そのものは削除されません
+- 記事をほかのミニサイトに移すと、カテゴリーは外れます
+- カテゴリーごとの RSS も使えます（例: `rss.xml?category=press`）
+- Tangled のリポジトリを元にしたミニサイトでは、サイト内カテゴリーは使えません
+
+## ほかのサイトに記事の一覧を表示する
+
+ミニサイトの最新記事を、会社のサイトなどほかのウェブサイトに表示できます。カテゴリーで絞り込んだ一覧を表示することもできます。
+
+→ **会社のサイトにお知らせを表示する（サイトへの埋め込み）**
+
 ## 次のステップ
 
 気になるユーザーの記事を見つけたら、フォローしてみましょう。
diff --git a/08-site-embed.md b/08-site-embed.md
new file mode 100644
index 0000000..e6004b8
--- /dev/null
+++ b/08-site-embed.md
@@ -0,0 +1,241 @@
+# 会社のサイトにお知らせを表示する（サイトへの埋め込み）
+
+ミニサイトの最新記事を、会社のサイトなど**ほかのウェブサイトに表示できる**機能です。
+HTML に2行貼るだけで、「お知らせ」や「プレスリリース」の一覧を設置できます。
+
+ニュース欄のためだけに WordPress などの CMS を用意する必要はありません。
+サイト本体は静的な HTML のまま、更新が必要な部分だけを mochott で書いて公開できます。CMS のアップデートやセキュリティ対策の手間も減らせます。
+
+<!-- スクリーンショット: 会社のサイトにお知らせ一覧が表示されている例 -->
+
+## できること
+
+- 会社のサイトのトップページなどに、ミニサイトの最新記事の一覧を表示します
+- 表示する件数や、カテゴリー（「プレスリリース」だけ、など）を指定できます
+- 記事をクリックすると、mochott のミニサイトにある記事のページが開きます。ミニサイトに独自ドメイン（例: `news.example.com`）を設定していれば、そちらのページが開きます
+- 一覧の見た目は、サイトのデザインに合わせて変えられます
+- 表示できるのは、**あなたが所有を確認したサイトだけ**です。ほかの人のサイトに勝手に埋め込まれて、公式の情報のように見せかけられることはありません
+
+## 準備するもの
+
+- お知らせ用のミニサイト（まだなければ「ミニサイトを作る」を参照してください）
+- 表示したいサイトの HTML を編集できること
+- そのサイトに確認用のファイルを置けること、または DNS を設定できること（どちらか一方）
+
+> **おすすめ**: 記事の詳細ページも自社のドメインで見せたい場合は、ミニサイトに独自ドメイン（例: `news.example.com`）を設定しておくと、一覧のリンク先がそのドメインになります。
+
+## 設置の手順
+
+### 1. ミニサイトのカテゴリーを用意する（必要な場合）
+
+「お知らせ」「プレスリリース」「IR」のように分けて表示したい場合は、ミニサイトのカテゴリーを用意します。
+
+- ミニサイトの設定画面の「サイト内カテゴリー」でまとめて作れます
+- 記事のエディタや、ミニサイトの記事管理の画面で、カテゴリー名を入力してその場で作ることもできます
+
+カテゴリーを使わない場合は、この手順は飛ばしてかまいません。
+
+### 2. 埋め込みを有効にする
+
+1. ダッシュボードのメニューから「ミニサイト」を選び、お知らせ用のミニサイトの設定を開きます。
+2. 下のほうにある「サイトへの埋め込み」で、「埋め込みを有効にする」をクリックします。
+3. 「貼り付けるコード」が表示されます。表示件数とカテゴリーを選ぶと、コードに反映されます。
+
+<!-- スクリーンショット: サイトへの埋め込みの設定画面 -->
+
+コードは次のような2行です。`key` の値はミニサイトごとに異なります。
+
+```html
+<script type="module" src="https://mochott.site/embed/v1.js"></script>
+<mochott-news key="emk_xxxxxxxxxxxxxxxxxxxxxxxx" limit="5"></mochott-news>
+```
+
+### 3. 表示するサイトを登録して、所有を確認する
+
+1. 「表示を許可するサイト」に、表示したいサイトのオリジンを入力します。
+   - オリジンとは `https://www.example.com` のように、`https://` とドメイン名だけの部分です（`/news` などのパスは含めません）
+   - `https://example.com` と `https://www.example.com` は別のサイトとして扱われます。両方で表示する場合は、両方を登録してください
+2. 確認方法を「ファイルを置く」か「DNS に TXT を追加」から選び、「追加」をクリックします。
+3. 表示された手順に従って、確認用の値を公開します。
+
+**ファイルを置く場合**
+
+表示された URL（`https://www.example.com/.well-known/mochott-embed.txt`）で、表示された1行だけを書いたテキストファイルを公開します。
+
+```text
+mochott-embed=（表示された値）
+```
+
+**DNS に TXT を追加する場合**
+
+ドメインの管理画面で、次の TXT レコードを追加します。
+
+| 名前 | 値 |
+| --- | --- |
+| `_mochott-embed.www.example.com` | `mochott-embed=（表示された値）` |
+
+4. 公開できたら「確認する」をクリックします。「確認済み」になれば完了です。
+
+確認は**一度だけ**です。確認が済んだら、ファイルや DNS のレコードは削除してもかまいません。
+
+> **ヒント**: DNS の設定はドメインを管理している部署や会社しか変更できないことがよくあります。サイトにファイルを置けるなら「ファイルを置く」のほうが手早く済みます。
+
+### 4. コードを貼る
+
+お知らせを表示したい場所に、手順2のコードを貼り付けます。
+
+```html
+<section class="news">
+  <h2>お知らせ</h2>
+  <script type="module" src="https://mochott.site/embed/v1.js"></script>
+  <mochott-news key="emk_xxxxxxxxxxxxxxxxxxxxxxxx" limit="5">
+    <a href="https://news.example.com/">お知らせ一覧へ</a>
+  </mochott-news>
+</section>
+```
+
+`<mochott-news>` の中に書いたリンクは、記事を読み込むまでの間や、JavaScript が動かない環境で表示されます。お知らせ一覧へのリンクを書いておくのがおすすめです。
+
+同じページに `<mochott-news>` を複数置くこともできます（`<script>` の行は1回で十分です）。
+
+## 設定できる項目
+
+| 属性 | 内容 |
+| --- | --- |
+| `key` | 埋め込みキー（必須）。設定画面に表示されたものを使います |
+| `limit` | 表示件数。1〜20（省略すると10） |
+| `category` | カテゴリーで絞り込みます。ミニサイトで作ったカテゴリーの ID を指定します |
+| `loading="lazy"` | 画面に近づいてから読み込みます。ページの下のほうに置く場合に |
+
+## 見た目を整える
+
+### 標準の表示を調整する
+
+標準の表示は、日付・カテゴリー・タイトルの一覧です。文字の書体と色は、置いた場所のものをそのまま引き継ぎます。
+
+色や余白は、CSS の変数で変えられます。
+
+```css
+mochott-news {
+  --mochott-accent: #0b5cad;          /* カテゴリー名の色 */
+  --mochott-border: #e5e7eb;          /* 記事の間の線の色 */
+  --mochott-gap: 16px;                /* 記事ごとの上下の余白 */
+}
+```
+
+さらに細かく変えたい場合は、`::part()` で各部分にスタイルを当てられます。
+
+```css
+mochott-news::part(title) { font-weight: 700; }
+mochott-news::part(date) { font-family: monospace; }
+```
+
+使える部分の名前は `list`・`item`・`link`・`meta`・`date`・`category`・`title` です。
+
+### サイトのデザインに合わせて表示する（テンプレート）
+
+`<mochott-news>` の中に `<template>` を書くと、そのマークアップで1件ずつ表示します。サイトのいまの HTML と CSS をそのまま使えます。
+
+```html
+<mochott-news key="emk_xxxxxxxxxxxxxxxxxxxxxxxx" limit="5" category="press">
+  <a href="https://news.example.com/">プレスリリース一覧へ</a>
+  <ul class="news-list" data-list></ul>
+  <template>
+    <li class="news-list__item">
+      <a class="news-list__link" data-field-href>
+        <time class="news-list__date" data-field="date"></time>
+        <span class="news-list__category" data-field="category"></span>
+        <span class="news-list__title" data-field="title"></span>
+      </a>
+    </li>
+  </template>
+</mochott-news>
+```
+
+| 指定 | 入る値 |
+| --- | --- |
+| `data-field="title"` | 記事のタイトル |
+| `data-field="date"` | 公開日（`2026.10.08` の形式。`<time>` 要素なら `datetime` 属性も入ります） |
+| `data-field="category"` | カテゴリー名 |
+| `data-field="excerpt"` | 記事の概要 |
+| `data-field="image"` | カバー画像の URL（`<img>` 要素の `src` に入ります） |
+| `data-field-href` | 記事の URL（`href` 属性に入ります） |
+| `data-list` | 記事を並べる入れ物。省略すると `<mochott-news>` の中に直接並べます |
+
+- 値がない項目（カテゴリーのない記事のカテゴリー欄など）は、その要素ごと取り除かれます
+- 値はすべて文字として入るので、記事のタイトルに HTML のタグが含まれていても、そのまま文字として表示されます
+- 記事を読み込むと、`<template>` と `data-list` 以外の中身（一覧へのリンクなど）は取り除かれます
+
+## Content-Security-Policy を設定しているサイトの場合
+
+サイトで CSP を設定している場合は、次の2つに `https://mochott.site` を追加してください。
+
+```text
+script-src  https://mochott.site
+connect-src https://mochott.site
+```
+
+カバー画像を表示する場合は、`img-src` にも `https://mochott.site` を追加してください。
+
+## 長く使うために
+
+コーポレートサイトは、一度作ったら何年も手を入れずに動き続けることが大切です。サイトへの埋め込みは、そのように作られています。
+
+- 所有の確認は一度だけです。定期的な再確認はありません
+- 埋め込みキーに有効期限はありません
+- mochott に長い間ログインしなくても、表示は止まりません
+- このページのコード（`/embed/v1.js`）は、今後も同じ書き方で動き続けるように維持します
+
+表示が止まるのは、次の場合だけです。
+
+- 「表示を許可するサイト」からそのサイトを削除したとき
+- 埋め込みキーを作り直したとき（新しいコードに貼り替えが必要です）
+- 埋め込みを無効にしたとき
+- ミニサイトやアカウントを削除したとき
+
+記事を公開・編集すると、通常は1分ほどで埋め込みにも反映されます。
+
+## うまく表示されないとき
+
+ブラウザの開発者ツールのコンソールに、`[mochott-news]` で始まるメッセージが表示されます。
+
+| メッセージ | 原因と対処 |
+| --- | --- |
+| `… is not verified for this key` | そのサイトがまだ確認されていません。手順3で登録と確認をしてください。`https://example.com` と `https://www.example.com` のように、実際に表示しているアドレスと登録したものが一致しているかも確かめてください |
+| `request failed (404: unknown_key)` | 埋め込みキーが違うか、キーを作り直した・埋め込みを無効にした後のコードです。設定画面に表示されている最新のコードを貼ってください |
+| `request failed (404: unknown_category)` | `category` に指定した ID のカテゴリーがありません |
+| `request failed (400: invalid_limit)` | `limit` は 1〜20 の数字で指定してください |
+| `missing or malformed key attribute` | `key` 属性がないか、値が途中で切れています |
+| `network error` | 通信できませんでした。CSP の設定（上記）も確認してください |
+
+制作中に自分のパソコンで確認する場合、`http://localhost` と `http://127.0.0.1` では、サイトを登録しなくても表示されます。
+
+## 開発者向けの情報
+
+読み込みが終わると `mochott-news:load` イベント、失敗すると `mochott-news:error` イベントが `<mochott-news>` 要素で発生します。
+
+```js
+document.querySelector('mochott-news').addEventListener('mochott-news:load', (e) => {
+  console.log(e.detail.items.length);
+});
+```
+
+## よくある質問
+
+### 検索エンジンには載りますか？
+
+一覧は JavaScript で表示するので、一覧そのものより、リンク先の記事ページが検索結果に載ることを想定しています。記事ページは mochott（または独自ドメイン）の通常のページとして検索エンジンに読み込まれます。
+
+### 静的サイトジェネレーターや、ほかの CMS のサイトでも使えますか？
+
+使えます。最終的に出力される HTML に2行を書ければ、作り方は問いません。
+
+### 費用はかかりますか？
+
+無料で使えます。
+
+## 次のステップ
+
+カテゴリーや独自ドメインの設定については、こちらを参照してください。
+
+→ **ミニサイトを作る**
-- 
2.51.2