From cd7efb09c3ea2713cc3cea0fbcde9ce0b7a0fa06 Mon Sep 17 00:00:00 2001
From: mhenrixon <mikael@mhenrixon.com>
Date: Fri, 3 Jul 2026 08:57:26 +0200
Subject: [PATCH] =?UTF-8?q?feat(page):=20DocsUI::Markdown=20=E2=80=94=20GF?=
 =?UTF-8?q?M=20markdown=20islands=20for=20prose=20authoring?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Prose is the most-written doc content and the noisiest to hand-build from
p/code/plain calls. Ship DocsUI::Markdown: authors write a block of GFM and it
renders styled identically to DocsUI::Prose, with fenced code routed through
DocsUI::Code (Rouge).

It parses GFM with commonmarker (v2, comrak) and walks the AST emitting Phlex
nodes — it never `raw`s commonmarker's HTML. That gives Phlex-native escaping
(no html_safe on author text — Critical Rule 7; #{} renders literally), fenced
code delegated to DocsUI::Code, GFM tables with the kit's table classes, and the
exact Prose typography classes on the wrapper.

- DocsUI::Page gains `md(source)` — a lowercase method so `md <<~MD … MD` needs
  no parens (unlike Prose()/Example()).
- Raw HTML is dropped (html_block/html_inline AST nodes skipped) — no <script>,
  no passthrough, no config to enable it.
- Markdown headings render as styled h3/h4; structure + the TOC stay with
  DocsUI::Section.
- Tight vs loose lists honored (tight items have no <p> wrapper, matching GFM
  and the Prose `[&_ul>li]` styling).
- Source is normalized to UTF-8 at the boundary (commonmarker v2 raises on
  US-ASCII / nil.to_s).

Dogfooded: installation.rb's verbose prose blocks converted to `md` (one Prose()
kept on purpose to prove Prose stays supported). README gains an "Authoring with
Markdown" section (the <<~'MD' single-quote tip; Sections still own structure).

## Test Coverage

- spec/docs_ui/markdown_spec.rb (19 examples): paragraphs/strong/em/links with
  Prose classes; inline code; fenced ruby through Rouge (token spans); unknown +
  no-language fence → plaintext; GFM table with kit classes; headings demoted to
  h3/h4; tight lists; block quote + thematic break; strikethrough; <script>
  dropped; raw HTML block dropped; #{} literal; HTML-special escaping; nil/empty
  source; non-UTF-8 source; header-only table; the Page#md delegation.

## Verification
- [x] bundle exec rake (94 examples, 0 failures; 88.7% coverage) passes
- [x] bundle exec rubocop (39 files, no offenses) passes
- [x] cd docs && bun run build:css — table + Prose wrapper classes present in
      the build (whole gem tree is already @source-scanned; no @source inline
      needed)

Closes #9
---
 README.md                                 |  49 ++++++
 app/components/docs_ui/markdown.rb        | 165 ++++++++++++++++++
 app/components/docs_ui/page.rb            |   9 +
 docs-kit.gemspec                          |   4 +
 docs/app/views/docs/pages/installation.rb |  62 +++----
 spec/docs_ui/markdown_spec.rb             | 196 ++++++++++++++++++++++
 6 files changed, 448 insertions(+), 37 deletions(-)
 create mode 100644 app/components/docs_ui/markdown.rb
 create mode 100644 spec/docs_ui/markdown_spec.rb

diff --git a/README.md b/README.md
index 0f2b96e..7e509de 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@ A `DocsUI::` Phlex kit, configured once per site:
 | `DocsUI::Code` | Rouge-highlighted code block (any of Rouge's ~200 languages) with an inline theme. |
 | `DocsUI::Page` | Base class for a hand-authored doc page; renders inside `DocsUI::Shell`. |
 | `DocsUI::Header` / `Section` / `Prose` / `Callout` | The page-authoring kit. |
+| `DocsUI::Markdown` | GFM Markdown island — prose as Markdown, styled like `Prose`, fenced code through Rouge. |
 | `DocsUI::Example` | Base for a live example with `method_source`-extracted source. |
 
 Plus `DocsKit::Registry` (in-memory docs registry mixin), `DocsKit::NavItem`
@@ -100,6 +101,54 @@ class Views::Docs::Pages::Installation < DocsUI::Page
 end
 ```
 
+## Authoring with Markdown
+
+Prose is the most-written content type — and the noisiest to hand-build from
+`p`/`code`/`plain` calls. `DocsUI::Page` gives you `md(source)`: write a block of
+GitHub-Flavored Markdown and it renders styled identically to `DocsUI::Prose`,
+with fenced code routed through `DocsUI::Code` (Rouge).
+
+```ruby
+def content
+  DocsUI::Section("Configure") do
+    md <<~'MD'
+      Set `brand` and `themes` in the initializer. Everything that differs
+      between two sites is **configuration**, not markup:
+
+      - `brand` — the topbar/sidebar heading,
+      - `themes` — the ThemeSwitcher options.
+
+      ```ruby
+      DocsKit.configure { |c| c.brand = "My Docs" }
+      ```
+
+      | Option | Type   |
+      |--------|--------|
+      | brand  | String |
+      | themes | Array  |
+    MD
+  end
+end
+```
+
+That renders paragraphs, **bold**/*italic*, inline `code`, links, bullet/ordered
+lists, block quotes, GFM tables (with the kit's table classes), and
+strikethrough. A fenced ` ```ruby ` block is highlighted by Rouge exactly like a
+hand-written `DocsUI::Code`; an unknown fence language falls back to plaintext.
+
+Two things to know:
+
+- **`md` is a lowercase method, so `md <<~MD … MD` needs no parens** — unlike
+  `DocsUI::Prose()` / `DocsUI::Example()`, which take a block and so require the
+  empty-parens form.
+- **Use a single-quoted heredoc, `<<~'MD'`.** Then `#{…}` in your prose is
+  literal text (Phlex escapes author text — no `html_safe`, no interpolation).
+
+Markdown headings render as styled `h3`/`h4`. Document **structure and the "On
+this page" TOC still come from `DocsUI::Section`** — keep section titles as
+`Section`, and use Markdown headings only for sub-headings inside a section. Raw
+HTML in the Markdown source is dropped (no `<script>`, no passthrough).
+
 ## Scaffold a new docs site in one command
 
 ```bash
diff --git a/app/components/docs_ui/markdown.rb b/app/components/docs_ui/markdown.rb
new file mode 100644
index 0000000..793711d
--- /dev/null
+++ b/app/components/docs_ui/markdown.rb
@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "commonmarker"
+
+module DocsUI
+  # A Markdown "island" for prose authoring inside a Phlex page. Parses GFM with
+  # commonmarker (v2, comrak) and walks the AST emitting Phlex nodes — it never
+  # `raw`s commonmarker's HTML. That buys three things:
+  #
+  #   * Phlex-native escaping — author text is escaped by Phlex, so no html_safe
+  #     on free text (Critical Rule 7) and #{} in prose renders literally.
+  #   * Fenced code delegated to DocsUI::Code (Rouge, configured aliases,
+  #     plaintext fallback) — highlighted identically to a hand-written Code block.
+  #   * The exact DocsUI::Prose typography classes on the wrapper, so Markdown
+  #     prose is visually identical to hand-authored Prose.
+  #
+  #   render DocsUI::Markdown.new(<<~MD)
+  #     Write **prose** as GFM. Fenced blocks are highlighted:
+  #
+  #     ```ruby
+  #     puts "hi"
+  #     ```
+  #   MD
+  #
+  # Raw HTML in the source is dropped (the AST's html_block/html_inline nodes are
+  # skipped) — there is no config to enable it. Headings render as styled h3/h4;
+  # document structure and the TOC stay with DocsUI::Section.
+  class Markdown < Phlex::HTML
+    # Reuse Prose's child-selector typography vocabulary verbatim so Markdown and
+    # hand-authored Prose read identically.
+    CLASSES = Prose::CLASSES
+
+    # The kit table wrapper + daisyUI table classes (matches DocsUI's table look).
+    TABLE_WRAPPER = "not-prose my-4 overflow-x-auto rounded-box border border-base-300"
+    TABLE_CLASSES = "table table-sm table-zebra"
+
+    def initialize(source)
+      # commonmarker v2 raises unless the text is UTF-8. Author heredocs already
+      # are, but nil.to_s / a US-ASCII string would crash the render — normalize
+      # at the boundary so any input parses.
+      @source = source.to_s.encode(Encoding::UTF_8)
+    end
+
+    def view_template
+      div(class: CLASSES) { visit(document) }
+    end
+
+    private
+
+    def document
+      Commonmarker.parse(@source)
+    end
+
+    # Emit each child of a node in order.
+    def visit_children(node)
+      node.each { |child| visit(child) }
+    end
+
+    # Dispatch a node to its handler (node_<type>). A node type with no handler
+    # just recurses into its children; html_block/html_inline have handlers that
+    # drop them (see below).
+    def visit(node)
+      handler = "node_#{node.type}"
+      respond_to?(handler, true) ? send(handler, node) : visit_children(node)
+    end
+
+    def node_document(node) = visit_children(node)
+
+    def node_paragraph(node)
+      p { visit_children(node) }
+    end
+
+    # Demote so Markdown headings never collide with the page masthead/section
+    # headings: h1→h3, h2→h4, anything deeper caps at h4.
+    def node_heading(node)
+      case node.header_level
+      when 1 then h3 { visit_children(node) }
+      else h4 { visit_children(node) }
+      end
+    end
+
+    def node_text(node) = plain(node.string_content)
+
+    def node_strong(node)
+      strong { visit_children(node) }
+    end
+
+    def node_emph(node)
+      em { visit_children(node) }
+    end
+
+    def node_strikethrough(node)
+      del { visit_children(node) }
+    end
+
+    def node_code(node)
+      code { node.string_content }
+    end
+
+    # Fenced code goes through DocsUI::Code so it is highlighted (Rouge) exactly
+    # like a hand-written block. No fence language falls back to plaintext.
+    def node_code_block(node)
+      lexer = node.fence_info.to_s.strip
+      lexer = "plaintext" if lexer.empty?
+      render DocsUI::Code.new(node.string_content, lexer:)
+    end
+
+    def node_link(node)
+      a(href: node.url) { visit_children(node) }
+    end
+
+    def node_list(node)
+      node.list_type == :ordered ? ol { visit_children(node) } : ul { visit_children(node) }
+    end
+
+    # In a tight list, GFM renders items WITHOUT a <p> wrapper (and Prose styles
+    # `li` directly). Unwrap the item's paragraph children when the parent list is
+    # tight; a loose list keeps the paragraphs (spacing between items).
+    def node_item(node)
+      tight = node.parent&.list_tight
+      li do
+        node.each do |child|
+          tight && child.type == :paragraph ? visit_children(child) : visit(child)
+        end
+      end
+    end
+
+    def node_block_quote(node)
+      blockquote { visit_children(node) }
+    end
+
+    def node_thematic_break(_node) = hr
+
+    def node_softbreak(_node) = whitespace
+
+    def node_linebreak(_node) = br
+
+    # A GFM table: the first row is the header (th), the rest are body cells (td).
+    def node_table(node)
+      rows = node.to_a
+      div(class: TABLE_WRAPPER) do
+        table(class: TABLE_CLASSES) do
+          thead { table_row(rows.first, header: true) } if rows.any?
+          tbody { rows.drop(1).each { |row| table_row(row) } } if rows.length > 1
+        end
+      end
+    end
+
+    def table_row(row, header: false)
+      tr do
+        row.each do |cell|
+          if header
+            th { visit_children(cell) }
+          else
+            td { visit_children(cell) }
+          end
+        end
+      end
+    end
+
+    # Raw HTML is dropped — no live tags from author Markdown.
+    def node_html_block(_node) = nil
+    def node_html_inline(_node) = nil
+  end
+end
diff --git a/app/components/docs_ui/page.rb b/app/components/docs_ui/page.rb
index adcebad..1f9ff6d 100644
--- a/app/components/docs_ui/page.rb
+++ b/app/components/docs_ui/page.rb
@@ -54,6 +54,15 @@ def view_template
       end
     end
 
+    # Render a block of GFM Markdown as Prose-styled prose (see DocsUI::Markdown).
+    # A lowercase method + heredoc sidesteps the parens-with-blocks gotcha:
+    #   md <<~'MD'
+    #     Write **prose** as Markdown. Single-quoted heredoc so #{} stays literal.
+    #   MD
+    def md(source)
+      render DocsUI::Markdown.new(source)
+    end
+
     # Override in subclasses for the lead paragraph (optional).
     def lead = nil
 
diff --git a/docs-kit.gemspec b/docs-kit.gemspec
index 6c3c5e0..c2379e6 100644
--- a/docs-kit.gemspec
+++ b/docs-kit.gemspec
@@ -57,6 +57,10 @@ Gem::Specification.new do |s|
   s.add_dependency "rails_icons", "~> 1.1"
   # Syntax highlighting for Docs::Code.
   s.add_dependency "rouge", ">= 4.0"
+  # GFM parsing for DocsUI::Markdown (v2 = Rust/comrak, precompiled; GFM tables +
+  # strikethrough + autolink on by default). We walk its AST to Phlex nodes, so
+  # commonmarker never renders HTML we'd have to html_safe.
+  s.add_dependency "commonmarker", "~> 2.0"
   s.add_dependency "zeitwerk", "~> 2.6"
 
   # phlex-reactive (reactive demos) and pgbus (Postgres-SSE transport) are
diff --git a/docs/app/views/docs/pages/installation.rb b/docs/app/views/docs/pages/installation.rb
index 050a393..0a049ef 100644
--- a/docs/app/views/docs/pages/installation.rb
+++ b/docs/app/views/docs/pages/installation.rb
@@ -23,21 +23,18 @@ def new_site_section
             DocsUI::Code(<<~SHELL, lexer: :shell)
               docs-kit new my-docs --image OWNER/REPO --service my-repo
             SHELL
-            DocsUI::Prose() do
-              p do
-                plain "This runs "
-                code { "rails new" }
-                plain " (propshaft + importmap + turbo/stimulus, no database) and applies the docs-kit template, which:"
-              end
-              ul do
-                li { "adds the gem and its dependencies," }
-                li { "runs the install generator," }
-                li { "syncs the lucide icons," }
-                li { "builds the Tailwind CSS, and" }
-                li { "scaffolds the Kamal deploy." }
-              end
-              p { "Then boot it:" }
-            end
+            md <<~'MD'
+              This runs `rails new` (propshaft + importmap + turbo/stimulus, no
+              database) and applies the docs-kit template, which:
+
+              - adds the gem and its dependencies,
+              - runs the install generator,
+              - syncs the lucide icons,
+              - builds the Tailwind CSS, and
+              - scaffolds the Kamal deploy.
+
+              Then boot it:
+            MD
             DocsUI::Code(<<~SHELL, lexer: :shell)
               cd my-docs && bin/dev
             SHELL
@@ -58,7 +55,7 @@ def existing_app_section
         end
 
         def existing_app_gemfile
-          DocsUI::Prose() { p { strong { "1. Add the gems." } } }
+          md "**1. Add the gems.**"
           DocsUI::Code(<<~RUBY, filename: "Gemfile")
             gem "docs-kit"
             gem "daisyui", require: "daisy_ui"
@@ -66,42 +63,31 @@ def existing_app_gemfile
             gem "rails_icons", "~> 1.1"
             gem "rouge"
           RUBY
-          DocsUI::Prose() do
-            p do
-              plain "Then run "
-              code { "bundle install" }
-              plain "."
-            end
-          end
+          md "Then run `bundle install`."
         end
 
         def existing_app_generator
-          DocsUI::Prose() { p { strong { "2. Run the install generator." } } }
+          md "**2. Run the install generator.**"
           DocsUI::Code(<<~SHELL, lexer: :shell)
             rails g docs_kit:install
           SHELL
-          DocsUI::Prose() do
-            p do
-              plain "It creates the initializers (phlex, rails_icons, docs_kit), includes "
-              code { "DocsKit::Controller" }
-              plain ", a "
-              code { "Doc" }
-              plain " registry with a sample page, the Bun/Tailwind CSS build ("
-              code { "bin/build-css" }
-              plain "), and registers the Stimulus controller. It is idempotent — safe to re-run."
-            end
-          end
+          md <<~'MD'
+            It creates the initializers (phlex, rails_icons, docs_kit), includes
+            `DocsKit::Controller`, a `Doc` registry with a sample page, the
+            Bun/Tailwind CSS build (`bin/build-css`), and registers the Stimulus
+            controller. It is idempotent — safe to re-run.
+          MD
         end
 
         def existing_app_icons
-          DocsUI::Prose() { p { strong { "3. Sync the icons." } } }
+          md "**3. Sync the icons.**"
           DocsUI::Code(<<~SHELL, lexer: :shell)
             rails g rails_icons:sync --library=lucide
           SHELL
         end
 
         def existing_app_css
-          DocsUI::Prose() { p { strong { "4. Build the CSS." } } }
+          md "**4. Build the CSS.**"
           DocsUI::Code(<<~SHELL, lexer: :shell)
             bun install && bun run build:css
           SHELL
@@ -121,6 +107,8 @@ def requirements_section
           end
         end
 
+        # Kept as a Prose() block (not md) on purpose: this page mixes both
+        # authoring styles to prove Prose stays fully supported alongside md.
         def verify_section
           DocsUI::Section("Verify") do
             DocsUI::Prose() do
diff --git a/spec/docs_ui/markdown_spec.rb b/spec/docs_ui/markdown_spec.rb
new file mode 100644
index 0000000..ceb405f
--- /dev/null
+++ b/spec/docs_ui/markdown_spec.rb
@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+RSpec.describe DocsUI::Markdown do
+  def render_md(source)
+    described_class.new(source).call
+  end
+
+  it "wraps output in the Prose typography classes" do
+    html = render_md("Just a paragraph.")
+
+    # The wrapper reuses DocsUI::Prose's child-selector vocabulary so Markdown
+    # prose is styled identically to hand-authored Prose.
+    expect(html).to include("text-base-content/80")
+    expect(html).to include("[&_p]:my-4")
+    expect(html).to include("[&_code]:bg-base-300")
+  end
+
+  it "renders paragraphs, strong, em, and links" do
+    html = render_md("A **bold** and *italic* word, plus a [link](https://example.com).")
+
+    expect(html).to include("<p>")
+    expect(html).to include("<strong>bold</strong>")
+    expect(html).to include("<em>italic</em>")
+    expect(html).to include('<a href="https://example.com">link</a>')
+  end
+
+  it "renders inline code as a <code> element (gets the [&_code] Prose treatment)" do
+    html = render_md("Call `bundle install` first.")
+
+    expect(html).to include("<code>bundle install</code>")
+  end
+
+  it "routes a fenced ```ruby block through DocsUI::Code (Rouge)" do
+    html = render_md(<<~MD)
+      ```ruby
+      puts "hi"
+      ```
+    MD
+
+    # DocsUI::Code's hallmarks: the .code-highlight wrapper and a Rouge token span.
+    expect(html).to include("code-highlight")
+    expect(html).to include("<pre>")
+    # Rouge emits token classes on spans (e.g. .s2 for a double-quoted string).
+    expect(html).to match(/<span class="[a-z0-9]+">/)
+  end
+
+  it "falls back to plaintext for an unknown fence language (never raises)" do
+    expect do
+      html = render_md(<<~MD)
+        ```wut-lang
+        not a real language
+        ```
+      MD
+      expect(html).to include("code-highlight")
+      expect(html).to include("not a real language")
+    end.not_to raise_error
+  end
+
+  it "renders a fenced block with no language through Code as plaintext" do
+    html = render_md(<<~MD)
+      ```
+      plain fenced text
+      ```
+    MD
+
+    expect(html).to include("code-highlight")
+    expect(html).to include("plain fenced text")
+  end
+
+  it "renders a GFM table with the kit's table classes" do
+    html = render_md(<<~MD)
+      | Name | Type |
+      |------|------|
+      | brand | String |
+    MD
+
+    expect(html).to include("<table")
+    expect(html).to include("<th")
+    expect(html).to include("<td")
+    expect(html).to include("brand")
+    expect(html).to include("String")
+    # The first row is the header (GFM semantics).
+    expect(html.index("Name")).to be < html.index("brand")
+  end
+
+  it "demotes headings — h1 becomes h3, h2 becomes h4, deeper stays h4" do
+    html = render_md("# Big\n\n## Medium\n\n#### Deep")
+
+    expect(html).to include("<h3>Big</h3>")
+    expect(html).to include("<h4>Medium</h4>")
+    expect(html).to include("<h4>Deep</h4>")
+    expect(html).not_to include("<h1")
+    expect(html).not_to include("<h2")
+  end
+
+  it "renders bullet and ordered lists" do
+    html = render_md("- one\n- two\n\n1. first\n2. second")
+
+    expect(html).to include("<ul>")
+    expect(html).to include("<ol>")
+    expect(html).to include("<li>one</li>")
+    expect(html).to include("<li>first</li>")
+  end
+
+  it "renders a block quote and a thematic break" do
+    html = render_md("> a quoted line\n\n---")
+
+    expect(html).to include("<blockquote>")
+    expect(html).to include("a quoted line")
+    expect(html).to include("<hr")
+  end
+
+  it "renders GFM strikethrough" do
+    html = render_md("This is ~~gone~~.")
+
+    expect(html).to include("<del>gone</del>")
+  end
+
+  it "drops raw HTML — <script> never appears in the output" do
+    html = render_md("Before <script>alert(1)</script> after.")
+
+    # The executable tag is dropped (AST html_inline nodes are skipped). The
+    # inner text may remain as inert, escaped text — but never as a live tag.
+    expect(html).not_to include("<script>")
+    expect(html).not_to include("</script>")
+    expect(html).to include("Before")
+    expect(html).to include("after")
+  end
+
+  it "drops a raw HTML block entirely" do
+    html = render_md("Text.\n\n<div onclick=\"evil()\">boom</div>")
+
+    expect(html).not_to include("<div onclick")
+    expect(html).not_to include("onclick")
+    expect(html).to include("Text.")
+  end
+
+  it "renders interpolation-looking text literally (Phlex escaping, no html_safe)" do
+    # A literal that LOOKS like Ruby interpolation but is plain author text.
+    literal = ["#", "{user}"].join
+    html = render_md("Use #{literal} in a template.")
+
+    expect(html).to include(literal)
+  end
+
+  it "escapes HTML-special characters in author text" do
+    html = render_md("A < B && C > D")
+
+    expect(html).to include("&lt;")
+    expect(html).to include("&gt;")
+    expect(html).to include("&amp;")
+  end
+
+  it "renders an empty wrapper for nil or empty source (never raises)" do
+    expect { described_class.new(nil).call }.not_to raise_error
+    expect(described_class.new("").call).to include("</div>")
+  end
+
+  it "normalizes a non-UTF-8 source (commonmarker requires UTF-8)" do
+    ascii = "Plain ASCII prose.".encode(Encoding::US_ASCII)
+
+    expect { render_md(ascii) }.not_to raise_error
+    expect(render_md(ascii)).to include("Plain ASCII prose.")
+  end
+
+  it "renders a header-only table without a body (no drop error)" do
+    html = render_md("| a | b |\n|---|---|")
+
+    expect(html).to include("<table")
+    expect(html).to include("<th")
+    expect(html).not_to include("<td")
+  end
+
+  # The `md(source)` helper on DocsUI::Page delegates to this component. Page
+  # itself needs a Rails view context (Shell composes CSRF/url helpers) and can't
+  # load standalone, so exercise the exact delegation through a bare Phlex host
+  # that includes the same DocsUI kit a Page does.
+  describe "the DocsUI::Page#md helper delegation" do
+    def render_md_helper(source)
+      md_source = source
+      Class.new(Phlex::HTML) do
+        include DocsUI
+
+        define_method(:md) { |src| render DocsUI::Markdown.new(src) }
+        define_method(:view_template) { md(md_source) }
+      end.new.call
+    end
+
+    it "renders Prose-styled Markdown from a page body" do
+      html = render_md_helper("A **markdown** paragraph.")
+
+      expect(html).to include("text-base-content/80") # the Prose wrapper classes
+      expect(html).to include("<strong>markdown</strong>")
+    end
+  end
+end