Add RubyKaigi 2026 talk prep: outline, research, and slides

- Slide outline with 33-slide structure across 3 sections:
  caught up (Aliki, server mode, Prism), getting there
  (Markdown, RBS), and getting ahead (AI evaluation)
- HTML presentation in Swiss Modern style with inline editing
- Research files: PR history for ruby/rdoc and ruby/ruby,
  llms.txt adoption data, call-seq vs RBS comparison,
  Markdown/RDoc coupling analysis, tompng's Prism work
- Google Slides Apps Script as alternative (populate_slides.js)

Author: st0012

populate_slides.js

@@ -0,0 +1,64 @@
+# call-seq vs RBS: Can We Replace call-seq?
+
+## The Overlap
+
+Both express method signatures for documentation purposes:
+
+```
+# call-seq:
+#   readlines(sep=$/)     -> array
+#   readlines(limit)      -> array
+#   readlines(sep, limit) -> array
+```
+
+```ruby
+#: (?String sep) -> Array[String]
+#: (Integer limit) -> Array[String]
+#: (String sep, Integer limit) -> Array[String]
+```
+
+| Aspect | call-seq | RBS `#:` |
+|--------|----------|----------|
+| Multiple signatures/overloads | Yes (multiple lines) | Yes (multiple `#:` lines) |
+| Argument names | Yes (`sep`, `limit`) | Yes (named params in RBS) |
+| Return type | Yes (arrow notation) | Yes (formal type) |
+| Parameter types | Implicit/prose | Explicit (String, Integer) |
+| Default values | **YES** (`sep=$/`) | **NO** |
+| Block/yield | Can describe | Formal block signature |
+| Machine-readable | No (free-form text) | Yes (parseable by RBS tools) |
+
+## The Gap: Default Values
+
+call-seq from Ruby core (C extensions):
+```c
+/*  call-seq:
+ *    commercial(cwyear, cweek=1, cwday=1, sg=nil) -> Date
+ */
+```
+
+RBS cannot express `cweek=1` — only that the parameter is optional:
+```ruby
+#: (Integer cwyear, ?Integer cweek, ?Integer cwday, ?Symbol? sg) -> Date
+```
+
+The default value `1` is lost.
+
+## Why This Matters
+
+- In ruby/ruby, C extension methods have no Ruby source — call-seq is the ONLY way to document their signatures
+- call-seq is free-form text (hard to parse, easy to get wrong, inconsistent across contributors)
+- RBS is structured and machine-readable (enables type linking, validation, tooling)
+- For a language that "doesn't want typing," using type signatures for documentation is a significant philosophical shift
+
+## The Open Questions
+
+1. Can RBS syntax be extended to support default values? (e.g., `?Integer cweek = 1`)
+2. What's the migration path for thousands of existing call-seq entries in ruby/ruby?
+3. Should call-seq remain for cases RBS can't express (version-specific overloads, prose descriptions)?
+
+## Sources
+
+- call-seq parsing: lib/rdoc/comment.rb `extract_call_seq` (lines 95-120)
+- call-seq storage: lib/rdoc/code_object/any_method.rb `call_seq=`
+- Real examples: test/rdoc/rdoc_comment_test.rb (ARGF.readlines, Date.commercial)
+- RBS inline syntax: https://sorbet.org/docs/rbs-comments

research/callseq_vs_rbs.md

@@ -0,0 +1,176 @@
+# RDoc Current Feature State (branch: stan-talk-prep)
+
+Research for RubyKaigi talk preparation. Based on code at `/Users/hung-wulo/src/github.com/Shopify/rdoc-talk-prep`.
+
+---
+
+## 1. Aliki Theme
+
+**What it is:** A modern, from-scratch HTML theme that subclasses `RDoc::Generator::Darkfish`. Authored by Stan Lo. Located at `lib/rdoc/generator/aliki.rb` with templates in `lib/rdoc/generator/template/aliki/`.
+
+### How it differs from Darkfish
+
+| Feature | Darkfish | Aliki |
+|---------|----------|-------|
+| Layout | Two-column (sidebar + content) | Three-column (sidebar + content + right-side TOC) |
+| Dark mode | None | Full dark mode with `data-theme` toggle, localStorage persistence, and system preference detection |
+| CSS size | 702 lines, ships embedded fonts (Lato, SourceCodePro) | 1994 lines, uses system font stack (no embedded fonts = lighter output) |
+| CSS architecture | Flat styles | Design system with CSS custom properties (tokens for colors, spacing, typography, shadows, transitions, z-index) |
+| JS files | 2 files (260 lines total: darkfish.js, search.js) | 7 files: aliki.js, theme-toggle.js, search_controller.js, search_navigation.js, search_ranker.js, c_highlighter.js, bash_highlighter.js |
+| Search | Basic search.js | Custom ranked search with fuzzy matching, namespace/method-aware queries, tiered scoring (exact > prefix > substring > fuzzy), type-aware priority, search snippets, type badges |
+| Search index | Uses JsonIndex generator (separate pass) | Built-in `write_search_index` / `build_search_index` (no extra generator needed), writes `js/search_data.js` |
+| Mobile | No specific mobile support | Responsive grid layout, mobile search modal, hamburger sidebar toggle, viewport-aware JS |
+| Syntax highlighting | None for C or shell code | Client-side C highlighter (keywords, types, macros, strings, preprocessor directives, Ruby C API types like VALUE/ID) and bash/shell highlighter (prompts, commands, options, strings, env vars, comments) |
+| TOC | Server-side sidebar TOC only | Auto-generated right-sidebar "On This Page" TOC from headings with IntersectionObserver scroll-spy, smooth scrolling |
+| Code blocks | Plain `<pre>` | Copy-to-clipboard buttons dynamically added to all `<pre>` elements |
+| Header/Footer | Minimal | Top navbar with brand, search bar, theme toggle; customizable footer via `footer_content` option in `.rdoc_options` |
+| Open Graph / SEO | None | Full Open Graph and Twitter Card meta tags, canonical URL support, rich `<meta>` descriptions |
+| Icons | Silk icon sprites (images/) | Inline SVG symbol sprites (no image files) |
+| Breadcrumbs | Yes | Yes (same approach) |
+| Method entries | Standard list | Styled as "signature cards" (commit dc7a1679) |
+| Ancestor tree | Shows parent class only | Full ancestor chain with recursive nested `<ul>` |
+| Source language | `<pre>` (no class) | `<pre class="c">` or `<pre class="ruby">` via `method.source_language` - enables language-specific highlighting |
+
+### Key design decisions
+- Sidebar is hidden by default with `hidden` attribute, shown by JS on large viewports. This avoids sidebar flicker on mobile page load.
+- Search data is written as `.js` (not `.json`) to avoid CORS issues when viewing generated docs via `file://` protocol.
+- `resolve_url(rel_prefix, url)` helper ensures absolute URLs pass through unchanged while relative URLs get prefixed correctly.
+
+---
+
+## 2. Markdown Support (GFM)
+
+**Parser:** `lib/rdoc/markdown.kpeg` (PEG grammar compiled to `lib/rdoc/markdown.rb`).
+
+### Default extensions enabled
+- `definition_lists` - PHP Markdown Extra style
+- `github` - fenced code blocks, syntax highlighting, tables, strikethrough
+- `html` - raw HTML blocks
+- `notes` - footnotes
+- `strike` - `~~strikethrough~~`
+
+### GFM features supported
+- Fenced code blocks (triple backtick with optional language tag)
+- Tables (header, alignment, body rows with inline markdown in cells)
+- Strikethrough (`~~text~~`)
+- Auto-linking of bare URLs
+- Underscores in words are never treated as emphasis
+
+### `break_on_newline` extension
+- Converts all newlines into hard line breaks (GFM-style). Commit `d62b0321` enabled this by default. **Note:** it is listed as an extension but NOT in `DEFAULT_EXTENSIONS` in the kpeg source - it appears the default enablement may be done elsewhere or the commit was on a different branch.
+
+### Recent markdown improvements (from git log)
+- `bd0e544f` - Fix blockquote lazy continuation parsing
+- `d62b0321` - Enable `break_on_newline` by default
+- `c59a7a89` - Fix table parser consuming lines without pipes
+- `52b24c2d` - Implement escapes in Markdown-to-RDoc conversion
+- `0602d13b` - Align strikethrough with GitHub Markdown spec
+- `39f5a2d9` - Fix backslash handling in table cell code spans
+- `eaac67d3` - Support markdown syntax in table cells
+- `393c0e87` - Add comparison with GitHub Flavored Markdown spec
+
+### Markdown output (`lib/rdoc/markup/to_markdown.rb`)
+- `RDoc::Markup::ToMarkdown` converts RDoc's internal markup tree back to Markdown format
+- Subclasses `ToRdoc`, overrides heading markers to `#`/`##`/etc.
+- Handles lists (bullet, numbered, definition/label)
+
+### What is NOT supported
+- Task lists / checkboxes
+- GitHub-style alerts (`> [!NOTE]`, `> [!WARNING]`)
+- Autolinks without angle brackets (bare URL auto-linking is RDoc-specific, not the GFM autolink extension)
+
+---
+
+## 3. RBS Integration
+
+**Status: Not present in this branch.**
+
+Grep for `rbs`, `RBS`, `type_sig`, `rbs_` across `lib/` returned zero matches. There is no RBS type signature parsing, display, or integration in the generator, parser, or templates.
+
+The memory file mentions prior investigation into "RBS Integration Phase 1" with inline `#:` type sigs in HTML output, but this code is not on the current `stan-talk-prep` branch.
+
+---
+
+## 4. LLM/AI Support (llms.txt)
+
+**Status: Not present.**
+
+Grep for `llms`, `llm`, `LLM`, `llms.txt` across the entire codebase (`.rb` files and all files) returned zero relevant matches. There is no `llms.txt` generator, no LLM-friendly output format, and no AI-related features.
+
+---
+
+## 5. Server Mode (Live Reload)
+
+**File:** `lib/rdoc/server.rb` (394 lines)
+
+### Architecture
+- Invoked via `rdoc --server` (added in commit `3c6f5f6f`)
+- Uses Ruby's built-in `TCPServer` - no WEBrick, no external dependencies
+- Binds to `127.0.0.1:<port>`
+- Multi-threaded: one thread per client connection, plus a background file watcher thread
+- Uses the Aliki generator exclusively (`RDoc::Generator::Aliki`)
+
+### Live reload mechanism
+1. Background watcher thread polls source file mtimes every 1 second
+2. Detects modified, new, and deleted files
+3. On change: re-parses only changed files via `@rdoc.parse_file(f)`, clears stale contributions, refreshes generator data, invalidates page cache
+4. Injects a `<script>` polling snippet before `</body>` in every HTML response
+5. Browser polls `/__status` every 1 second, comparing `last_change` timestamp
+6. If timestamp changed, browser does `location.reload()`
+
+### Request routing
+- `/__status` - returns JSON `{last_change: <float>}` for live reload
+- `/css/*`, `/js/*` - serves static assets from Aliki template directory (with path traversal protection)
+- `/js/search_data.js` - dynamically generated search index
+- `/index.html` - calls `@generator.generate_index`
+- `/table_of_contents.html` - calls `@generator.generate_table_of_contents`
+- `/ClassName.html` - looks up class/module in store, renders via generator
+- `/filename.html` - looks up text page in store
+- 404s rendered through `generate_servlet_not_found`
+
+### Page caching
+- Pages are cached in `@page_cache` (hash)
+- Cache is fully invalidated on any file change (entire hash cleared)
+- Mutex protects all shared state (`@page_cache`, `@last_change_time`, store operations)
+
+### Terminal output
+- Prints clickable hyperlink to terminal using OSC 8 escape sequences
+- Logs `<status> <path> (<duration>ms)` for page requests
+- Logs re-parse timing: `Re-parsed <files> (<duration>ms)`
+- Status/asset requests are not logged (to reduce noise)
+
+### Recent fixes
+- `e4e332f2` - Print timing for page requests and re-parsing
+- `237f113d` - Fix deadlock on Ctrl+C
+- `78325e18` - Fix live reload for C files
+- `8323a434` - Fix page links returning 404
+
+---
+
+## 6. Markup Generator (`lib/rdoc/generator/markup.rb`)
+
+This is NOT a standalone generator - it is a mixin module (`RDoc::Generator::Markup`) included into `RDoc::CodeObject` and `RDoc::Context::Section`. It provides HTML rendering helpers used by the Darkfish/Aliki generators:
+
+- `description` - renders a CodeObject's comment as HTML
+- `formatter` - creates an `RDoc::Markup::ToHtmlCrossref` formatter for cross-reference linking
+- `aref_to(target_path)` / `as_href(from_path)` - relative URL generation between pages
+- `cvs_url(url, full_path)` - web repository link construction
+- `canonical_url` - builds canonical URL using `@store.options.canonical_root`
+- `RDoc::MethodAttr#markup_code` - converts token stream to HTML with optional line numbers
+- `RDoc::ClassModule#description` - renders from `@comment_location` (multi-file comment support)
+
+The separate `RDoc::Markup::ToMarkdown` class in `lib/rdoc/markup/to_markdown.rb` converts RDoc markup tree back to Markdown text output (headings, lists, etc.) but is not used by any generator for documentation output.
+
+---
+
+## Summary for Talk
+
+### Shipping / Ready
+1. **Aliki theme** - Complete modern theme with dark mode, responsive layout, three-column design, advanced search, C/bash syntax highlighting, copy-to-clipboard, SVG icons, Open Graph metadata, customizable footer
+2. **Server mode** - Zero-dependency live-reload server using TCPServer, file watching with incremental re-parsing, page caching
+3. **GFM improvements** - Tables with inline markdown, strikethrough aligned with GFM spec, blockquote fixes, fenced code blocks, GFM spec comparison tests
+
+### Not present
+4. **RBS integration** - No type signature display in generated docs
+5. **LLM support** - No `llms.txt` generation or LLM-friendly output
+6. **Markdown output generator** - `ToMarkdown` exists as a formatter but is not wired to any documentation output generator

research/current_features.md

@@ -0,0 +1,43 @@
+# llms.txt Adoption Research (for RubyKaigi talk)
+
+## Key Takeaway
+
+llms.txt has **no measurable impact** on AI citations. As an RDoc maintainer, the trade-off (generation time + code complexity) isn't worth the negligible benefit.
+
+## Adoption Numbers
+
+- **10.13%** of ~300,000 domains analyzed have an llms.txt file (SE Ranking study)
+- **~9 out of 10 websites** haven't adopted it
+- **0.3%** adoption among the top 1,000 most visited websites globally
+- Adoption is flat across traffic tiers: low (9.88%), mid (10.54%), high (8.27%)
+
+## Effectiveness: No Measurable Impact
+
+- **No correlation** between having llms.txt and AI citation frequency
+- XGBoost ML model **improved accuracy when llms.txt was removed** as a variable
+- Statistical methods used: Spearman correlation, XGBoost regression, SHAP analysis
+- From mid-Aug to late Oct 2025: llms.txt pages received **zero visits** from Google-Extended, GPTBot, PerplexityBot, or ClaudeBot
+
+## Platform Support
+
+- **No major LLM provider** currently supports llms.txt (not OpenAI, not Anthropic, not Google)
+- Google AI Overviews rely on traditional SEO signals, not llms.txt
+- OpenAI/Anthropic have not officially recognized it as a ranking signal
+
+## Sources
+
+- [SE Ranking: "LLMs.txt: Why Brands Rely On It and Why It Doesn't Work"](https://seranking.com/blog/llms-txt/)
+- [Search Engine Journal: "LLMs.txt Shows No Clear Effect On AI Citations, Based On 300k Domains"](https://www.searchenginejournal.com/llms-txt-shows-no-clear-effect-on-ai-citations-based-on-300k-domains/561542/)
+- [Rankability LLMS.txt Adoption Report](https://www.rankability.com/llms-report/)
+- [PPC.land: "llms.txt adoption stalls as major AI platforms ignore proposed standard"](https://ppc.land/llms-txt-adoption-stalls-as-major-ai-platforms-ignore-proposed-standard/)
+
+## Talk Framing
+
+This is a good example of **responsible maintainership** — evaluating hype vs. real impact before adding complexity. The data shows:
+
+1. The spec exists but nobody reads it (zero bot visits)
+2. Having it doesn't help (no citation correlation)
+3. Major platforms explicitly don't use it
+4. Adding it to RDoc would increase generation time and code complexity for all users
+
+**Better alternative**: Focus on making documentation itself better (Markdown migration, better structure, RBS types) — these improve docs for both humans AND AI consumption naturally.

research/llms_txt_adoption.md

@@ -0,0 +1,88 @@
+# Why Markdown Improvements Are Slow: The Shared IR Problem
+
+## The One-Line Summary
+
+Markdown doesn't have its own intermediate representation — it converts inline syntax to **RDoc markup strings**, which then get re-parsed by a shared inline parser. Fixing Markdown means not breaking RDoc markup, and vice versa.
+
+## The Architecture
+
+```
+                     Block-level parsing              Inline parsing            Rendering
+                     ─────────────────               ──────────────            ─────────
+Markdown source  ──► RDoc::Markdown.parse ──┐
+                     (markdown.kpeg)        │
+                                            ├──► RDoc::Markup::Document ──► InlineParser ──► ToHtml
+                                            │    (Paragraph, Heading,       (shared!)       (shared!)
+RDoc markup      ──► RDoc::Markup.parse  ──┘     List, Verbatim, etc.)
+                     (parser.rb)                  SAME NODE TYPES
+```
+
+## The Core Problem: Two-Phase Parsing
+
+When the Markdown parser encounters `**bold text**`, it does NOT produce a structured "bold" node. Instead:
+
+```ruby
+# lib/rdoc/markdown.kpeg, line 303
+def strong(text)
+  if text =~ /\A[a-z\d.\/-]+\z/i
+    "*#{text}*"              # → RDoc word-pair markup string
+  else
+    "<b>#{text}</b>"         # → RDoc HTML tag string
+  end
+end
+```
+
+The Markdown parser outputs **RDoc-formatted strings** inside `Paragraph` nodes. These strings are then re-parsed by `RDoc::Markup::InlineParser` — the same parser that handles RDoc markup's inline formatting.
+
+## Why This Makes Fixes Hard
+
+### 1. Shared InlineParser
+Any change to `InlineParser` (lib/rdoc/markup/inline_parser.rb) affects both Markdown and RDoc markup. Adding strikethrough support for Markdown required modifying the shared parser, which could break RDoc markup rendering.
+
+### 2. Escape Rules Are Coupled
+Markdown must escape RDoc-special characters when generating strings:
+
+```ruby
+# lib/rdoc/markdown.kpeg, line 309
+def rdoc_escape(text)
+  text.gsub(/[*+<\\_]/) {|s| "\\#{s}" }
+end
+```
+
+If InlineParser's escape handling changes, Markdown's escape generation breaks.
+
+### 3. Shared Formatters
+All rendering goes through the same `RDoc::Markup::Formatter` subclasses (ToHtml, ToHtmlCrossref, ToRdoc, etc.). Changes to formatters must work for documents produced by both parsers.
+
+### 4. Cross-References Are Unified
+Both formats share the same cross-reference linking system via `regexp_handling` in `ToHtmlCrossref`. Link resolution behavior can't diverge between formats.
+
+## Concrete Examples of Cross-Format Breakage
+
+| Fix | What happened |
+|-----|---------------|
+| **Strikethrough** (Jan 2026) | Markdown parsed `~~text~~` correctly but InlineParser didn't recognize `~` as delimiter or `<del>` tags. Had to modify shared InlineParser. |
+| **Backtick quoting** (Jan 2026) | Extended backtick support — had to work in both Markdown and RDoc markup contexts |
+| **Table parsing** (Nov 2024) | Markdown table parser's special behavior affected general parsing |
+| **Escape handling** (Aug 2024) | Markdown escapes had to align with InlineParser's escape rules |
+
+## What Would Fix This
+
+The ideal fix: give Markdown its own structured inline representation instead of outputting RDoc strings. But this would require:
+- A parallel inline node system or tagged nodes that carry format origin
+- Separate formatter paths for Markdown-originated vs RDoc-originated content
+- Massive test infrastructure changes
+
+This is a fundamental architectural debt from RDoc's original design, where Markdown was bolted on as a second input format that feeds into a pipeline designed for one format.
+
+## tompng's InlineParser Rewrite (Jan 2026)
+
+The replacement of `AttributeManager` with `InlineParser` (PR #1559) was a step forward — it moved from string-replacing macros to structured inline nodes. But the Markdown parser still outputs RDoc-formatted strings that feed into this shared parser, so the coupling remains.
+
+## Talk Framing
+
+This explains why:
+1. **Markdown improvements take so long** — every fix must be tested against both formats
+2. **The fix space is constrained** — sometimes the "right" Markdown fix would break RDoc markup
+3. **It's a 15+ year architectural decision** — Markdown was added to RDoc around 2011-2012, reusing the existing pipeline rather than building a parallel one
+4. **Progress is real but incremental** — GFM spec comparison (#1550), strikethrough, heading anchors, table fixes all chipped away at this