red_quilt 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a53fcc10d442493f6de26bbced9811a9f54e5328fbfa3aae39e44491bcbdf99c
-  data.tar.gz: 6b0f0be3ccf229a341421f08a3b5eaa6b95bc99ed14a1d0e02a7c4675e9e100e
+  metadata.gz: 45de1415fe8cc64323b390d8cedc4d6691fa6c0ab17337fac8aa956cef8bd107
+  data.tar.gz: c3392372dd65fe74149678dbb9b5ebc8cc389b6f44ca4b0013e6eadfd565568d
 SHA512:
-  metadata.gz: f919427e21c232babe5c5672e125928557d09a5b3e80fe70a6902913cc0c1796d7478cc180edcbde2cb8b5c861c94d8b0d4fb4a5ece5f876d795b17c4a6ff891
-  data.tar.gz: da179b152732e9cfffb8c7580a550191f5d0798a5d6a62be8b2fab17bc4c33fd6725b1a2ebdcf001ad38bba8681030e7f27f7d036cfc68dab0ee96e61e43cb53
+  metadata.gz: c7f3c0226e9a2e2cac06273147dfd497f45566ba99d766cee30ccd6fbff728669ab1d9ab112c93de33cce405e2cea9c8789e4f431a70c10d546e2bc2309c8c5b
+  data.tar.gz: 69cae77089c64fbf8821cc6340e0c0ad8749004fbf03ec5acf1b55daa388404db5a64a276f48267ab9e58a66a21eb2892b9f120b942e105930862c94e29de7fe

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-05-29
+
+### Added
+
+- Optional Tilt template adapter, registered for the common markdown
+  extensions (`.md`, `.markdown`, …).
+- Opt-in heading anchor ids via the `heading_ids:` option on `render_html` /
+  `Document#to_html`. Slugs follow GitHub's scheme but preserve Unicode, so
+  non-ASCII (e.g. Japanese) headings stay readable; duplicates within a
+  document get `-1`, `-2`, … suffixes.
+
+### Fixed
+
+- `require "red_quilt/cli"` on its own now works (cli.rb requires red_quilt).
+
+### Internal
+
+- Add LICENSE and gemspec metadata; move the API reference to `docs/api.md`.
+
 ## [0.6.1] - 2026-05-29
 
 ### Added

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Masayoshi Takahashi (takahashim)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -37,85 +37,78 @@ RedQuilt.render_html("Hi <em>tag</em>", allow_html: true)
 # => "<p>Hi <em>tag</em></p>\n"
 ```
 
-## API Reference
+### Options
+
+`RedQuilt.parse` and `RedQuilt.render_html` accept:
 
-### Document
+| Option | Default | Effect |
+|--------|---------|--------|
+| `allow_html:` | `false` | Pass raw HTML through instead of escaping it |
+| `disallow_raw_html:` | `false` | With `allow_html`, still neutralize GFM's dangerous tags (`<script>`, `<iframe>`, …) |
+| `extended_autolinks:` | `false` | GFM: linkify bare `http(s)://` / `www.` / email addresses |
+| `footnotes:` | `false` | GFM footnotes (see below) |
+| `lint:` | `false` | Collect lint diagnostics (empty links, missing image alt, heading-level skips) |
+
+### Footnotes (opt-in)
 
 ```ruby
-doc = RedQuilt.parse("# Title\n\nBody")
-
-doc.root              # Root node (NodeRef)
-doc.walk              # Traverse all nodes (block: { |node| ... } or Enumerator)
-doc.to_html           # Render as HTML
-doc.to_ast            # Export complete AST as Hash
-doc.to_json           # Export as MDAST-compatible JSON
-doc.to_mdast          # Export as MDAST Hash
-doc.source_map        # Line/column lookup (lazy memoized)
-doc.allow_html?       # Check HTML pass-through setting
+RedQuilt.render_html(<<~MD, footnotes: true)
+  Here is a reference.[^1]
+
+  [^1]: And the footnote text.
+MD
+# The reference becomes a superscript link, and a trailing
+# <section class="footnotes"> lists the referenced definitions (in
+# first-reference order) with backrefs.
 ```
 
-### NodeRef (AST node wrapper)
+### Diagnostics
 
-```ruby
-node = doc.root.children.first
+Parsing never raises on malformed input; warnings are collected on the document.
 
-# Traversal
-node.type             # :heading, :paragraph, :link, etc. (Symbol)
-node.children         # Array[NodeRef]
-node.walk             # Enumerator[NodeRef] or { |node| ... } block
-node.find_all(:link)  # Array[NodeRef] with matching type
-node.text             # String (concatenated child text)
+```ruby
+doc = RedQuilt.parse("[x](javascript:alert(1))", lint: true)
+doc.diagnostics.map(&:rule)   # => [:unsafe_url]
+doc.diagnostics.first.severity # => :warning
+```
 
-# Position information (byte offset)
-node.source_span      # SourceSpan with start_byte, end_byte
+### Heading anchors (opt-in)
 
-# Position information (line/column)
-node.source_location  # { start_line, start_column, end_line, end_column }
-                      # line: 1-indexed, column: 0-indexed (character-based)
+`render_html` / `to_html` accept `heading_ids:` to give every heading a
+slugified `id` for anchor links. Slugs follow GitHub's scheme but keep Unicode
+intact, so Japanese headings stay readable; duplicates get `-1`, `-2` suffixes.
 
-# AST export
-node.to_h             # Export subtree as Hash[Symbol, untyped]
+```ruby
+RedQuilt.render_html("# Hello World\n\n## はじめに", heading_ids: true)
+# => "<h1 id=\"hello-world\">Hello World</h1>\n<h2 id=\"はじめに\">はじめに</h2>\n"
 ```
 
-### SourceSpan
+### Tilt integration
+
+RedQuilt ships a [Tilt](https://github.com/jeremyevans/tilt) adapter.
+NOTE: It is not loaded by default; require it explicitly and add `tilt` to your own bundle:
 
 ```ruby
-span = node.source_span
-span.start_byte       # Integer (0-indexed byte offset)
-span.end_byte         # Integer (exclusive)
-span.length           # Computed: end_byte - start_byte
+require "red_quilt/tilt"
+
+Tilt.new("page.md").render          # => HTML
+Tilt.new("page.md", footnotes: true).render
 ```
 
-## Supported Syntax
-
-### Block elements
-
-- Paragraphs: Plain text blocks
-- Headings: ATX headings (`# Title`)
-- Thematic breaks: `---`, `***`, `___`
-- Code blocks: Indented and fenced (with info string)
-- Block quotes: `> quote text`
-- Lists: Ordered (`1.`) and unordered (`-`, `*`, `+`)
-- List items: Nested blocks, tight/loose detection
-- Tables: GFM syntax with header/body rows
-- Raw HTML blocks: 7 types (script, comment, etc.)
-- Link reference definitions: `[foo]: /url "title"`
-
-### Inline elements
-
-- Text: Plain strings
-- Emphasis/Strong: `*em*`, `**strong**`, `_em_`, `__strong__`
-- Code spans: `` `code` ``
-- Links: `[text](/url)`, `[text](/url "title")`, reference links
-- Images: `![alt](/url)`, `![alt](/url "title")`, reference images
-- Soft/Hard line breaks: Implicit (soft) and explicit `\` or two spaces
-- Raw HTML inline: `<a href="#">link</a>`
-- Autolinks: `<http://example.com>`, `<user@example.com>`
-- Character references: `&amp;`, `&#x27;`, etc.
+Native options (`allow_html:`, `footnotes:`, …) pass straight through; Tilt's `escape_html:` convention is also honored.
+
+## Documentation
+
+- [API reference](docs/api.md) — `Document` / `NodeRef` / `SourceSpan`, supported syntax, and usage examples
+- [Architecture overview](docs/architecture.ja.md) (日本語)
+- [Arena usage guide](docs/arena-usage.ja.md) (日本語)
+- [CommonMark conformance notes](docs/commonmark-conformance.ja.md) (日本語)
 
 ## CommonMark Compatibility
 
 RedQuilt achieves 100% compliance with the CommonMark v0.31.2 specification.
+See the [conformance notes](docs/commonmark-conformance.ja.md) for GFM
+extensions and intentional deviations.
 
 ## Command-line Tool
 
@@ -139,8 +132,11 @@ redquilt --format json input.md
 # Standalone HTML document with title
 redquilt --standalone --title "My Document" input.md
 
-# Enable GFM extended autolinks
-redquilt --extended-autolinks input.md
+# Enable GFM extended autolinks / footnotes
+redquilt --extended-autolinks --footnotes input.md
+
+# Standalone page with the bare template (no embedded CSS)
+redquilt --theme none input.md
 ```
 
 ### Options
@@ -148,12 +144,16 @@ redquilt --extended-autolinks input.md
 ```
 --format FORMAT          Output format: html (default), ast, json
 --allow-html             Pass raw HTML through to the output
+--disallow-raw-html      With --allow-html, filter GFM's dangerous tags
 --extended-autolinks     Linkify bare URLs and email addresses (GFM)
+--footnotes              Enable GFM footnotes
+--lint                   Collect lint diagnostics
 --[no-]standalone        Wrap HTML in full document (default: on)
 --auto-title             Use the first heading's text as <title>
 --title TITLE            Explicit <title> text
 --lang LANG              html lang attribute (default: "en")
 --css URL                Add a stylesheet link
+--theme THEME            Embedded stylesheet: default (default) or none
 --diagnostics            Print diagnostics to stderr
 --diagnostics-only       Print diagnostics only (suppress output)
 -h, --help               Show help
@@ -187,6 +187,8 @@ In link/image destinations, only these schemes are permitted:
 
 All other schemes (`javascript:`, `data:`, `vbscript:`, etc.) are blocked by replacing the URL with an empty string.
 
+Autolinks (`<scheme:...>`) follow CommonMark and allow arbitrary schemes, so they use a denylist instead: only the script-executing schemes `javascript:`, `vbscript:`, and `data:` are blocked.
+
 ### Opting into HTML pass-through
 
 ```ruby
@@ -196,50 +198,6 @@ RedQuilt.render_html(user_markdown, allow_html: true)
 # This passes HTML blocks and inline tags through unchanged
 ```
 
-## Usage Examples
-
-### Extract all headings
-
-```ruby
-doc = RedQuilt.parse(source)
-headings = doc.root.find_all(:heading)
-
-headings.each do |node|
-  level = node.to_h[:attributes][:level]
-  text = node.text
-  puts "#{'#' * level} #{text}"
-end
-```
-
-### Walk the AST with line numbers
-
-```ruby
-doc = RedQuilt.parse(source)
-
-doc.root.walk do |node|
-  loc = node.source_location
-  if loc
-    puts "#{node.type} at line #{loc[:start_line]}"
-  end
-end
-```
-
-### Export and transform
-
-```ruby
-doc = RedQuilt.parse("# Title\n\nBody with [link](/url)")
-ast = doc.to_ast
-
-# Print AST structure (for debugging)
-pp ast
-
-# Process nodes
-doc.root.find_all(:link).each do |link|
-  attrs = link.to_h[:attributes]
-  puts "Link: #{link.text} → #{attrs[:destination]}"
-end
-```
-
 ## Development
 
 ### Running tests

data/docs/api.md

@@ -0,0 +1,132 @@
+# RedQuilt API Reference
+
+Detailed API, supported syntax, and usage examples. For installation and a
+quick start, see the [README](../README.md).
+
+## Document
+
+```ruby
+doc = RedQuilt.parse("# Title\n\nBody")
+
+doc.root              # Root node (NodeRef)
+doc.walk              # Traverse all nodes (block: { |node| ... } or Enumerator)
+doc.to_html           # Render as HTML (see options below)
+doc.to_ast            # Export complete AST as Hash
+doc.to_json           # Export as MDAST-compatible JSON
+doc.to_mdast          # Export as MDAST Hash
+doc.source_map        # Line/column lookup (lazy memoized)
+doc.diagnostics       # Array of RedQuilt::Diagnostic collected while parsing
+doc.allow_html?       # Check HTML pass-through setting
+doc.disallow_raw_html? # Check GFM disallowed-raw-HTML filtering setting
+
+# Standalone document with an embedded theme:
+doc.to_html(standalone: true, theme: :default, title: "My Doc", lang: "en")
+# theme: :default (compact, dark-mode-aware stylesheet) or :none (bare).
+# css: "style.css" links an external stylesheet instead.
+```
+
+## NodeRef (AST node wrapper)
+
+```ruby
+node = doc.root.children.first
+
+# Traversal
+node.type             # :heading, :paragraph, :link, etc. (Symbol)
+node.children         # Array[NodeRef]
+node.walk             # Enumerator[NodeRef] or { |node| ... } block
+node.find_all(:link)  # Array[NodeRef] with matching type
+node.text             # String (concatenated child text)
+
+# Position information (byte offset)
+node.source_span      # SourceSpan with start_byte, end_byte
+
+# Position information (line/column)
+node.source_location  # { start_line, start_column, end_line, end_column }
+                      # line: 1-indexed, column: 0-indexed (character-based)
+
+# AST export
+node.to_h             # Export subtree as Hash[Symbol, untyped]
+```
+
+## SourceSpan
+
+```ruby
+span = node.source_span
+span.start_byte       # Integer (0-indexed byte offset)
+span.end_byte         # Integer (exclusive)
+span.length           # Computed: end_byte - start_byte
+```
+
+## Supported Syntax
+
+### Block elements
+
+- Paragraphs: Plain text blocks
+- Headings: ATX headings (`# Title`)
+- Thematic breaks: `---`, `***`, `___`
+- Code blocks: Indented and fenced (with info string)
+- Block quotes: `> quote text`
+- Lists: Ordered (`1.`) and unordered (`-`, `*`, `+`)
+- List items: Nested blocks, tight/loose detection
+- Tables: GFM syntax with header/body rows
+- Raw HTML blocks: 7 types (script, comment, etc.)
+- Link reference definitions: `[foo]: /url "title"`
+- Footnote definitions: `[^label]: …` (GFM, opt-in via `footnotes: true`)
+
+### Inline elements
+
+- Text: Plain strings
+- Emphasis/Strong: `*em*`, `**strong**`, `_em_`, `__strong__`
+- Strikethrough: `~~text~~` (GFM)
+- Code spans: `` `code` ``
+- Links: `[text](/url)`, `[text](/url "title")`, reference links
+- Images: `![alt](/url)`, `![alt](/url "title")`, reference images
+- Soft/Hard line breaks: Implicit (soft) and explicit `\` or two spaces
+- Raw HTML inline: `<a href="#">link</a>`
+- Autolinks: `<http://example.com>`, `<user@example.com>`
+- Footnote references: `[^label]` (GFM, opt-in via `footnotes: true`)
+- Character references: `&amp;`, `&#x27;`, etc.
+
+## Usage Examples
+
+### Extract all headings
+
+```ruby
+doc = RedQuilt.parse(source)
+headings = doc.root.find_all(:heading)
+
+headings.each do |node|
+  level = node.to_h[:attributes][:level]
+  text = node.text
+  puts "#{'#' * level} #{text}"
+end
+```
+
+### Walk the AST with line numbers
+
+```ruby
+doc = RedQuilt.parse(source)
+
+doc.root.walk do |node|
+  loc = node.source_location
+  if loc
+    puts "#{node.type} at line #{loc[:start_line]}"
+  end
+end
+```
+
+### Export and transform
+
+```ruby
+doc = RedQuilt.parse("# Title\n\nBody with [link](/url)")
+ast = doc.to_ast
+
+# Print AST structure (for debugging)
+pp ast
+
+# Process nodes
+doc.root.find_all(:link).each do |link|
+  attrs = link.to_h[:attributes]
+  puts "Link: #{link.text} → #{attrs[:destination]}"
+end
+```

data/docs/{architecture.md → architecture.ja.md}

@@ -14,7 +14,7 @@ Source (Markdown String)
    │     (list.rb, blockquote.rb, reference_definition.rb)
    │
    ▼Arena (raw inline spans)
-   │paragraph / heading / table cellの本文はbyte spanのみで保持
+   │paragraph / heading / table cellの本文はbyte spanまたはstr1 literalで保持
    │
    ▼InlinePass                       (lib/red_quilt/inline_pass.rb)
    │     ├─Inline::Lexer              (lib/red_quilt/inline/lexer.rb)
@@ -47,9 +47,9 @@ CommonMark§2.3/2.4の最小前処理。`\r\n`/`\r`→`\n`の行末正規化と
 
 ### InlinePass / Lexer / Builder
 - 対象選定: paragraph / heading / table cellの各inline targetを走査して処理。
-- Lexer: targetのbyte spanをスキャンしTokens(parallel array)へ。
+- Lexer: targetのbyte span、またはstr1 literalの範囲をスキャンしTokens(parallel array)へ。
 - Builder①linear pass: code span / link / image / autolink / 簡易inlineを解決。
-- Builder②process_emphasis: delimiter stackを畳んでemphasis / strongを確定(CommonMark§6.2)。
+- Builder②process_emphasis: delimiter stackを畳んでemphasis / strong / strikethroughを確定(CommonMark§6.2、strikethroughはGFM拡張)。
 - footnote参照: `[^label]`を`FootnoteRegistry`で解決し、初回参照順に採番して`FOOTNOTE_REFERENCE`を生成。
 
 ### FootnotePass (`footnotes: true`)

data/docs/{arena-usage.md → arena-usage.ja.md}

@@ -78,19 +78,19 @@ Arenaの扱いのポイントは以下になります。
 
 ---
 
-## 1.設計の要点
+## 1. 設計の要点
 
 ArenaはASTを「オブジェクトのツリー」ではなく[parallel array](https://en.wikipedia.org/wiki/Parallel_array)として表現します。
 
--ノードは整数ID(`node_id`)で識別されます
--各IDに対応する属性(parent / source span / payload)はそれぞれ異なるArrayに列として保持します
--ノードの追加は各Arrayの末尾への代入操作だけで完結し、新しいRubyオブジェクトは一切生成しません
+- ノードは整数ID(`node_id`)で識別されます
+- 各IDに対応する属性(parent / source span / payload)はそれぞれ異なるArrayに列として保持します
+- ノードの追加は各Arrayの末尾への代入操作だけで完結し、新しいRubyオブジェクトは一切生成しません
 
 結果として、Arenaは以下のような性質を持ちます。
 
--ホットパスではIDというIntegerだけを取り回せる
--メモリ局所性が良く、GC圧が小さい
--ノードを「軽い」値として扱えるのでRenderer / Builderをinline化しやすい
+- ホットパスではIDというIntegerだけを取り回せる
+- メモリ局所性が良く、GC圧が小さい
+- ノードを「軽い」値として扱えるのでRenderer / Builderをinline化しやすい
 
 ###列(column)一覧
 
@@ -98,13 +98,13 @@ ArenaはASTを「オブジェクトのツリー」ではなく[parallel array](h
 |------|------|
 | `@type` | NodeType (Integer定数) |
 | `@parent` / `@first_child` / `@last_child` / `@next_sibling` / `@prev_sibling` |親・子・兄弟リンク。値はnode id (`NO_NODE`で「なし」) |
-| `@source_start` / `@source_len` | document source内のバイト範囲。`source_start < 0`は「spanなし、内容はstr1に持つ」を意味する|
+| `@source_start` / `@source_len` | document source内のバイト範囲。`source_start < 0`は「spanなし」を意味する|
 | `@int1` / `@int2` / `@int3` | NodeTypeごとに用途が決まる整数スロット(default `0`) |
 | `@str1` / `@str2` | NodeTypeごとに用途が決まる文字列スロット(default `nil`) |
 
 ---
 
-## 2.不変条件
+## 2. 不変条件
 
 Arenaを扱う上で常に成り立つ前提です。
 
@@ -117,7 +117,7 @@ Arenaを扱う上で常に成り立つ前提です。
 4. `NO_NODE` = -1
 親や兄弟が存在しないことを示すsentinelです。`Arena::NO_NODE`定数で参照できます。
 5. `source_start < 0`は「spanなし」
-この場合、ノードの内容は`@str1`にliteralとして持たれていることが期待されます(例: blockquoteを解除したparagraph、entityデコード後のTEXT)。
+この場合、leafノードの内容は`@str1`にliteralとして持つことが多いです(例: blockquoteを解除したparagraph、entityデコード後のTEXT)。ただしcontainer inlineのように、spanなしでも`str1`を使わず子ノードから内容を構成するNodeTypeもあります。
 
 ---
 
@@ -125,7 +125,7 @@ Arenaを扱う上で常に成り立つ前提です。
 
 Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図が掴みやすくなります。
 
-### 3.1構造の操作(mutators)
+### 3.1 構造の操作(mutators)
 
 ツリーを組み立て・編集するためのAPIです。`validなid`を渡す前提で、安全性チェックは最小限です。
 
@@ -139,7 +139,7 @@ Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図
 | `update_span(id, start_byte, end_byte)` | source spanを再設定|
 | `update_str1(id, value)` / `update_int3(id, value)` |個別slotの書き換え|
 
-### 3.2構造の参照(raw id accessors)
+### 3.2 構造の参照(raw id accessors)
 
 `NO_NODE`を返しうる、生のcolumn値を取り出します。命名規則`raw_X_id`は「戻り値がnode idで、-1 (`NO_NODE`)になる可能性がある」ことを示します。
 
@@ -149,7 +149,7 @@ Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図
 | `raw_first_child_id(id)` / `raw_last_child_id(id)` |子idか`NO_NODE` |
 | `raw_next_sibling_id(id)` / `raw_prev_sibling_id(id)` |兄弟idか`NO_NODE` |
 
-### 3.3ペイロードの参照(column accessors)
+### 3.3 ペイロードの参照(column accessors)
 
 各columnを生のまま返します。「sentinelが返り得る」ことは戻り値の型から読み取ってください。
 
@@ -161,7 +161,7 @@ Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図
 | `int1(id)` / `int2(id)` / `int3(id)` | Integer (default 0) |
 | `str1(id)` / `str2(id)` | String or `nil` |
 
-### 3.4セマンティックaccessor
+### 3.4 セマンティックaccessor
 
 低レベル列を解釈して「使いやすい値」を返します。`nil`を返しうるのは明示的に「無い」ことを表現するためです。
 
@@ -170,7 +170,7 @@ Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図
 | `source_span(id)` | `SourceSpan`か`nil` (spanなしの場合) |
 | `text(id)` | `str1`があればそれ、なければ`source.byteslice(...)`。どちらもなければ`nil` |
 
-### 3.5走査
+### 3.5 走査
 
 |メソッド|用途|
 |----------|------|
@@ -188,8 +188,8 @@ Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図
 | NodeType | int1 | int2 | int3 | str1 | str2 |
 |----------|------|------|------|------|------|
 | `DOCUMENT` | - | - | - | - | - |
-| `PARAGRAPH` | - | - | - | (transformed時のみ)結合済みliteral | - |
-| `HEADING` | level (1-6) | - | - | (transformed時のみ) inline literal | - |
+| `PARAGRAPH` | - | - | - | 必要時の結合済みliteral(transformed時、leading indent除去時など) | - |
+| `HEADING` | level (1-6) | - | - | 必要時のinline literal(transformed時、setext headingなど) | - |
 | `THEMATIC_BREAK` | - | - | - | - | - |
 | `BLOCKQUOTE` | - | - | - | - | - |
 | `LIST` | ordered? (0/1) | start_number | tight? (1=tight) | marker (`-`/`*`/`+`/`.`/`)`) | - |
@@ -222,12 +222,14 @@ Arenaの公開メソッドは以下の3レイヤーに分けて読むと意図
 ### Source spanの慣習
 
 - `source_start` / `source_len`: 元documentのbytes (絶対byte offset)
-- `source_start < 0`: spanなし。内容は`str1`にliteralとして持たれる(transformed paragraphやLexerのliteralモードで生じる)
-- blockノードは「自分のtext範囲」をspanとして持つ(`#`や`>`のprefixを除いた、内側のみ)
+- `source_start < 0`: spanなし。leafノードでは内容を`str1`にliteralとして持つことが多いが、container inlineは子ノードだけを持つ場合がある。
+- blockノードのspanは用途で2系統に分かれる。
+    - inline対象(paragraph / heading / table cell)のspanは、InlinePassがそのまま字句解析するbyte範囲を兼ねるため、`#`やprefixを除いたinline本文を指す。
+    - それ以外(list / blockquote / table / code / html block等)は字句解析に使われず、構造/行寄りの位置情報のみを持つ。
 
 ---
 
-## 5.典型的な使い方
+## 5. 典型的な使い方
 
 ### 5.1 Arenaを作って小さなASTを組み立てる
 
@@ -259,7 +261,7 @@ arena.text(inner_id)       # => "world"
 arena.source_span(em_id)   # => #<SourceSpan @start_byte=6 @end_byte=13>
 ```
 
-### 5.2兄弟をループする(ホットパス)
+### 5.2 兄弟をループする(ホットパス)
 
 ```ruby
 arena.each_child(para_id) do |child_id|
@@ -281,19 +283,26 @@ arena.child_ids(para_id).map { |id| arena.type_name(id) }
 # => [:text, :emphasis]
 ```
 
-### 5.3ノードを別の親に移動する
+### 5.3 ノードを別の親に移動する
+
+`reparent`は移動先ノードのchildrenを置き換えるAPIなので、移動先は新規作成した空ノードにするのが基本です。
 
 ```ruby
-# `em_id`の子を全部`para_id`直下に移す
+# `em_id`の子を新しいstrong_id直下に移す
+strong_id = arena.add_node(RedQuilt::NodeType::STRONG,
+                           source_start: arena.source_start(em_id),
+                           source_len: arena.source_len(em_id))
+arena.insert_before(arena.raw_parent_id(em_id), em_id, strong_id)
+
 first = arena.raw_first_child_id(em_id)
 last  = arena.raw_last_child_id(em_id)
-arena.reparent(para_id, first, last) if first != RedQuilt::Arena::NO_NODE
+arena.reparent(strong_id, first, last) if first != RedQuilt::Arena::NO_NODE
 
-# em_idを空のまま切り離す
+# em_idを空のまま切り離す。strong_idはem_idの位置に残る。
 arena.detach(em_id)
 ```
 
-### 5.4ノードを差し替える
+### 5.4 ノードを差し替える
 
 ```ruby
 # em_idをstrong_idに置換(中身はそのまま)
@@ -309,7 +318,7 @@ arena.reparent(strong_id, first, last) if first != RedQuilt::Arena::NO_NODE
 arena.detach(em_id)
 ```
 
-### 5.5列の値を直接更新する
+### 5.5 列の値を直接更新する
 
 ```ruby
 # headingのレベルはint1に入っているが、書き換え専用setterは無いので
@@ -323,7 +332,7 @@ arena.update_span(text_id, 0, 12)
 
 ---
 
-## 6.パフォーマンス上の注意
+## 6. パフォーマンス上の注意
 
 ####ホットパスでは`each_child`を使う
 
@@ -331,7 +340,7 @@ arena.update_span(text_id, 0, 12)
 
 #### `text(id)`はstr1を優先する
 
-余計な`byteslice`を起こさないため、可能な限り`str1`にliteralを持たせない(`nil`のまま)のが基本
+余計な`byteslice`を起こさないため、sourceから復元できる内容は`str1`を`nil`のままにするのが基本。ただしentity decode後のTEXT、code/html literal、table cell、transformed/literal inline targetなど、正しさのためにliteralが必要なケースでは`str1`を使う
 
 #### `source_span(id)`は`SourceSpan`を毎回allocateする
 
@@ -360,4 +369,3 @@ arena.update_span(text_id, 0, 12)
 #### `@source`を後から変えない
 
 仮にやると`text` / `source_span`の戻り値が静かに壊れる
-