diff --git a/app/components/docs_ui/code.rb b/app/components/docs_ui/code.rb
index dcc4286..c8b673d 100644
--- a/app/components/docs_ui/code.rb
+++ b/app/components/docs_ui/code.rb
@@ -13,8 +13,10 @@ module DocsUI
#
# Any language Rouge knows (~200 lexers) works by its name or alias — python,
# go, rust, elixir, kotlin, swift, json, dockerfile, ... — no allowlist. Add
- # friendly aliases/labels via DocsKit.configure (code_lexer_aliases). An unknown
- # language falls back to plaintext (never raises).
+ # friendly lexer aliases via DocsKit.configure (code_lexer_aliases). An unknown
+ # language falls back to plaintext (never raises). (Tab labels are a
+ # DocsUI::Example concern — set via code_language_labels, not here; Code has no
+ # label, only a filename.)
class Code < Phlex::HTML
include Phlex::Rails::Helpers::ContentSecurityPolicyNonce
@@ -53,7 +55,12 @@ def view_template
def csp_nonce = view_context && content_security_policy_nonce
def title_bar
- div(class: "flex items-center gap-2 border-b border-base-300 bg-base-300/60 px-4 py-2") do
+ # data-md-skip: the title bar is chrome. MarkdownExport strips it whole
+ # before the visitor runs, so the filename never leaks into the .md twin as
+ # a stray line above the fence. The visible HTML is unaffected (DROP_SELECTOR
+ # is applied only inside #to_md).
+ div(class: "flex items-center gap-2 border-b border-base-300 bg-base-300/60 px-4 py-2",
+ data: { md_skip: true }) do
render DocsUI::Icon.new("file-code", class: "size-3.5 opacity-60")
span(class: "font-mono text-xs opacity-70") { @filename }
end
diff --git a/app/components/docs_ui/error_table.rb b/app/components/docs_ui/error_table.rb
index 36f3032..5dcfb98 100644
--- a/app/components/docs_ui/error_table.rb
+++ b/app/components/docs_ui/error_table.rb
@@ -24,7 +24,7 @@ class ErrorTable < Phlex::HTML
def initialize(errors)
@errors = errors
- @with_param = errors.any? { |error| error[:param] }
+ @with_param = errors.any? { |error| present_param?(error[:param]) }
end
def view_template
@@ -49,7 +49,12 @@ def row(error)
def param_cell(error)
param = error[:param]
- param ? [:code, param] : NO_PARAM
+ present_param?(param) ? [:code, param] : NO_PARAM
+ end
+
+ # A blank string is not a param — it flips no column and gets the em-dash.
+ def present_param?(param)
+ !param.nil? && !param.to_s.strip.empty?
end
end
end
diff --git a/app/components/docs_ui/field_table.rb b/app/components/docs_ui/field_table.rb
index 4476344..8ced749 100644
--- a/app/components/docs_ui/field_table.rb
+++ b/app/components/docs_ui/field_table.rb
@@ -39,7 +39,7 @@ def row(field)
[:code, field.fetch(:name)],
field.fetch(:type),
field.fetch(:required, false) ? REQUIRED_YES : REQUIRED_NO,
- field.fetch(:description)
+ field.fetch(:description, REQUIRED_NO)
]
end
end
diff --git a/app/components/docs_ui/page.rb b/app/components/docs_ui/page.rb
index 77d62f7..51f8ce6 100644
--- a/app/components/docs_ui/page.rb
+++ b/app/components/docs_ui/page.rb
@@ -41,7 +41,7 @@ def eyebrow(value = nil)
# or :panel/:toggle/:sidebar to override per page.
def on_page(value = :__unset__)
@on_page = value unless value == :__unset__
- defined?(@on_page) ? @on_page : true
+ defined?(@on_page) ? @on_page : DocsKit.configuration.on_page_default
end
end
diff --git a/app/components/docs_ui/prop_table.rb b/app/components/docs_ui/prop_table.rb
index de8b3bc..67c6d6d 100644
--- a/app/components/docs_ui/prop_table.rb
+++ b/app/components/docs_ui/prop_table.rb
@@ -36,7 +36,7 @@ def view_template
# left as the author wrote it.
def code_first_column(cells)
first, *rest = cells
- first = [:code, first] unless first.is_a?(Array)
+ first = [:code, first] unless first.nil? || first.is_a?(Array)
[first, *rest]
end
end
diff --git a/app/components/docs_ui/request_example.rb b/app/components/docs_ui/request_example.rb
index 077c5eb..1fe819d 100644
--- a/app/components/docs_ui/request_example.rb
+++ b/app/components/docs_ui/request_example.rb
@@ -67,6 +67,8 @@ def merged_headers(auth_header)
return @headers if auth_header.nil? || auth_header.strip.empty?
name, value = auth_header.split(":", 2).map(&:strip)
+ return @headers if value.nil? || value.empty?
+
{ name => value }.merge(@headers)
end
diff --git a/app/components/docs_ui/section.rb b/app/components/docs_ui/section.rb
index 0110bd4..490d843 100644
--- a/app/components/docs_ui/section.rb
+++ b/app/components/docs_ui/section.rb
@@ -26,11 +26,14 @@ module DocsUI
class Section < Phlex::HTML
def initialize(title, id: nil, description: nil)
@title = title
- @id = id || slugify(title)
+ @explicit_id = id
@description = description
end
def view_template(&)
+ # Resolve the anchor id at render time so it can be de-duplicated against
+ # sibling sections sharing this page's render context (see #resolve_id).
+ @id = @explicit_id || unique_id(slugify(@title))
section(id: @id, class: "mb-10 scroll-mt-20") do
heading
description
@@ -73,5 +76,19 @@ def slugify(text)
text.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
end
+
+ # De-duplicate the anchor id across every Section on the page. Phlex's render
+ # `context` is a Hash shared by the whole render tree, so sibling sections see
+ # the same used-id counter without any shared parent state. A title that
+ # slugifies to "" (e.g. "C++" → "c" is fine, but "+++" → "") falls back to
+ # "section"; colliding bases get a "-1", "-2", … sequence suffix so in-page
+ # anchors and the auto-TOC/scroll-spy resolve to distinct headings.
+ def unique_id(base)
+ base = "section" if base.empty?
+ used = (context[:__docs_ui_section_ids__] ||= Hash.new(0))
+ n = used[base]
+ used[base] += 1
+ n.zero? ? base : "#{base}-#{n}"
+ end
end
end
diff --git a/app/components/docs_ui/sidebar.rb b/app/components/docs_ui/sidebar.rb
index f334732..1cc7cee 100644
--- a/app/components/docs_ui/sidebar.rb
+++ b/app/components/docs_ui/sidebar.rb
@@ -42,7 +42,7 @@ def nav_groups = config.nav_groups
def header_section
div(class: "flex min-h-16 items-center gap-2 px-4") do
- a(href: "/", class: "text-lg font-bold text-base-content") { config.brand }
+ a(href: config.brand_href, class: "text-lg font-bold text-base-content") { config.brand }
badge = config.version_badge_text
span(class: "badge badge-sm badge-ghost") { badge } if badge
end
diff --git a/app/components/docs_ui/table.rb b/app/components/docs_ui/table.rb
index 98c08f1..053b457 100644
--- a/app/components/docs_ui/table.rb
+++ b/app/components/docs_ui/table.rb
@@ -54,6 +54,9 @@ def render_cell(cell)
case cell
in [:code, value] then code(class: "text-sm") { plain value.to_s }
in [:md, value] then render DocsUI::Markdown.inline(value.to_s)
+ in [Symbol => _tag, *]
+ raise ArgumentError,
+ "DocsUI::Table: unknown or malformed typed cell #{cell.inspect}; use [:code, value] or [:md, value]"
else plain cell.to_s
end
end
diff --git a/lib/docs_kit/api_templates.rb b/lib/docs_kit/api_templates.rb
index 06e4d40..91c549f 100644
--- a/lib/docs_kit/api_templates.rb
+++ b/lib/docs_kit/api_templates.rb
@@ -83,7 +83,10 @@ def python(request)
# The body as compact single-line JSON, for inlining in a JS literal.
def compact_json(request)
require "json"
- JSON.generate(JSON.parse(request.pretty_body_json))
+ json = request.pretty_body_json
+ JSON.generate(JSON.parse(json))
+ rescue JSON::ParserError
+ json
end
end
end
diff --git a/lib/docs_kit/configuration.rb b/lib/docs_kit/configuration.rb
index eeaae54..a3086b0 100644
--- a/lib/docs_kit/configuration.rb
+++ b/lib/docs_kit/configuration.rb
@@ -3,7 +3,7 @@
module DocsKit
# Per-site configuration for the shared docs chrome. Everything that differs
# between two otherwise-identical docs sites lives here, so the Phlex shell
- # (Docs::Shell, Docs::Sidebar, Docs::ThemeSwitcher) is byte-identical across
+ # (DocsUI::Shell, DocsUI::Sidebar, DocsUI::ThemeSwitcher) is byte-identical across
# sites and only the config changes.
#
# DocsKit.configure do |c|
@@ -42,14 +42,22 @@ class Configuration
# A callable returning the sidebar nav as an ordered Hash of
# { "Heading" => { "Subgroup" => [items] } }. Each item must respond to
- # the duck type the Sidebar renders (see Docs::Sidebar#nav_link): #href,
+ # the duck type the Sidebar renders (see DocsUI::Sidebar#nav_link): #href,
# #label, and optional #icon. Defaults to an empty nav.
#
# Prefer #nav_registries for the common case — an explicit #nav lambda is
# only needed for bespoke nav (multiple registries interleaved, custom
# subgroups). When #nav is left at its default, the sidebar derives from
# #nav_registries instead.
- attr_accessor :nav
+ attr_reader :nav
+
+ # Assigning #nav marks it explicit, so #nav_groups uses it verbatim rather
+ # than deriving from #nav_registries — tracked by a flag, not object
+ # identity, so ANY assigned lambda wins (even one that resolves to {}).
+ def nav=(value)
+ @nav_explicit = true
+ @nav = value
+ end
# An ordered { "Heading" => registry_class } map. Each registry responds to
# .nav_items (Registry v2) → { group => [NavItem] } for its authored pages.
@@ -67,14 +75,14 @@ class Configuration
# stylesheets (e.g. a separate rouge theme) lists them here.
attr_accessor :stylesheets
- # The Rouge theme class used by Docs::Code for inline syntax-highlight CSS.
+ # The Rouge theme class used by DocsUI::Code for inline syntax-highlight CSS.
# This is the BASE (light) theme, emitted un-scoped so it applies to every
# theme unless a dark override wins (see #code_theme_dark).
attr_accessor :code_theme
# An optional second Rouge theme (String name or Class) used for the site's
# DARK daisyUI themes. Default nil → single-theme behavior, fully backwards
- # compatible. When set, Docs::Code additionally emits this theme's CSS scoped
+ # compatible. When set, DocsUI::Code additionally emits this theme's CSS scoped
# under [data-theme=X] .code-highlight for each shipped dark theme (see
# #dark_themes), so code blocks stay readable when the switcher flips to a
# dark theme — CSS-only, no JS, no flash.
@@ -103,7 +111,7 @@ class Configuration
# the brand.
attr_writer :nav_storage_key
- # The default "On this page" (auto-TOC) placement, used by Docs::Page when a
+ # The default "On this page" (auto-TOC) placement, used by DocsUI::Page when a
# page doesn't pass its own on_page:. One of the ON_PAGE_MODES, or false to
# render no auto-TOC by default.
attr_writer :on_page_default
@@ -118,7 +126,7 @@ class Configuration
# "plaintext" (no highlighting, never raises).
attr_accessor :code_lexer_fallback
- # Human labels for language tabs in Docs::Example, merged over the built-ins
+ # Human labels for language tabs in DocsUI::Example, merged over the built-ins
# (e.g. { elixir: "Elixir", curl: "cURL" }). Unknown tokens humanize.
attr_accessor :code_language_labels
@@ -209,10 +217,11 @@ def initialize
@title_suffix = nil
@themes = %w[dark light]
@default_theme = nil
- # The sentinel default nav lambda. #nav_groups treats it as "unset" and
- # derives the sidebar from #nav_registries instead; an explicit c.nav
- # replaces this object so the derivation steps aside (backwards compat).
+ # The default nav lambda. Until a site assigns #nav (which sets
+ # @nav_explicit), #nav_groups treats nav as "unset" and derives the sidebar
+ # from #nav_registries instead; an explicit c.nav (any lambda) then wins.
@nav = DEFAULT_NAV
+ @nav_explicit = false
@nav_registries = {}
@version_badge = nil
@stylesheets = %w[application]
@@ -360,42 +369,65 @@ def default_theme
# heading whose pages are all unauthored (empty nav_items) is dropped so no
# empty group renders.
def nav_groups
- return nav_groups_from_registries if @nav.equal?(DEFAULT_NAV)
+ return nav_groups_from_registries unless @nav_explicit
result = @nav.respond_to?(:call) ? @nav.call : @nav
result || {}
end
# The resolved version badge string, or nil.
+ # The rendered version badge. A callable is invoked; a plain String (or any
+ # non-nil value) is coerced to its string form — so `c.version_badge = "v1.2"`
+ # renders, not only a lambda.
def version_badge_text
- return unless @version_badge.respond_to?(:call)
+ return if @version_badge.nil?
+ return @version_badge.call if @version_badge.respond_to?(:call)
- @version_badge.call
+ @version_badge.to_s
end
- # The Rouge theme class resolved from #code_theme (String or class).
+ # The default Rouge theme both #code_theme_class and #code_theme_dark_class
+ # fall back to when a configured theme name can't be resolved — so a typo'd
+ # theme name degrades gracefully instead of raising on every code block.
+ DEFAULT_CODE_THEME = "Rouge::Themes::Monokai"
+
+ # The Rouge theme class resolved from #code_theme (String or class). A String
+ # name that doesn't resolve degrades to the default theme rather than raising
+ # NameError on every DocsUI::Code render.
def code_theme_class
return @code_theme if @code_theme.is_a?(Class)
- Object.const_get(@code_theme.to_s)
+ resolve_theme(@code_theme) || Object.const_get(DEFAULT_CODE_THEME)
end
# The dark Rouge theme class resolved from #code_theme_dark (String or
- # class), or nil when unset — mirrors #code_theme_class. Docs::Code emits
- # dark code CSS only when this is non-nil.
+ # class), or nil when unset — mirrors #code_theme_class. DocsUI::Code emits
+ # dark code CSS only when this is non-nil, so an unresolvable name degrades to
+ # nil (no dark restyle) rather than raising.
def code_theme_dark_class
return if @code_theme_dark.nil?
return @code_theme_dark if @code_theme_dark.is_a?(Class)
- Object.const_get(@code_theme_dark.to_s)
+ resolve_theme(@code_theme_dark)
end
# The dark themes the site actually ships: #dark_themes intersected with
- # #themes, in #themes declaration order. Docs::Code scopes the dark theme's
+ # #themes, in #themes declaration order. DocsUI::Code scopes the dark theme's
# CSS under [data-theme=X] for each of these, so a dark theme that isn't in
# the Tailwind build never emits dead CSS.
def dark_themes_shipped
Array(@themes) & Array(@dark_themes)
end
+
+ private
+
+ # Resolve a Rouge theme constant from its String name, returning nil (not
+ # raising) when the name doesn't resolve — a typo'd or unloaded theme must
+ # not crash every code block on the page.
+ def resolve_theme(name)
+ Object.const_get(name.to_s)
+ rescue NameError
+ nil
+ end
end
end
diff --git a/lib/docs_kit/markdown_export/blocks.rb b/lib/docs_kit/markdown_export/blocks.rb
index 44d5a09..5db1bb2 100644
--- a/lib/docs_kit/markdown_export/blocks.rb
+++ b/lib/docs_kit/markdown_export/blocks.rb
@@ -103,11 +103,16 @@ def blockquote(node)
quote(render(node))
end
- # A callout → `> **Label:** body` as a blockquote. The label comes from the
- # level; the body is the callout's inner text as inline Markdown.
+ # A callout → `> **Label:** body` as a blockquote. Callout stamps a
+ # `div.font-semibold` title (present only when title: is given) and a
+ # `div.text-sm` body. Read them separately: the author's title is the label
+ # when present (else the level label), and only the body div is rendered so
+ # the title never fuses into the body text.
def callout(node, level)
- label = CALLOUT_LABELS.fetch(level, "Note")
- body = @inline.render(node).strip
+ title = node.at_css(".font-semibold")
+ body_node = node.at_css(".text-sm") || node
+ label = title ? @inline.render(title).strip : CALLOUT_LABELS.fetch(level, "Note")
+ body = @inline.render(body_node).strip
quote("**#{label}:** #{body}")
end
diff --git a/lib/docs_kit/markdown_export/inline.rb b/lib/docs_kit/markdown_export/inline.rb
index 1130a00..98abd29 100644
--- a/lib/docs_kit/markdown_export/inline.rb
+++ b/lib/docs_kit/markdown_export/inline.rb
@@ -43,7 +43,7 @@ def render_node(node)
# any other wrapper recurses so its text survives.
def element(node, name)
case name
- when "code" then "`#{node.text}`"
+ when "code" then code_span(node.text)
when "a" then link(node)
when "img" then image(node)
when "br" then " \n"
@@ -67,6 +67,15 @@ def heading_text(node)
private
+ # A GFM-correct inline code span. The fence is a backtick run one longer
+ # than the longest run inside the text, so an interior backtick can never
+ # close the span; a space pads content that starts or ends with a backtick.
+ def code_span(text)
+ fence = "`" * ((text.scan(/`+/).map(&:length).max || 0) + 1)
+ pad = text.start_with?("`") || text.end_with?("`") ? " " : ""
+ "#{fence}#{pad}#{text}#{pad}#{fence}"
+ end
+
def self_anchor?(node)
node.element? && node.name == "a" && node["href"].to_s.start_with?("#")
end
diff --git a/lib/docs_kit/markdown_export/table.rb b/lib/docs_kit/markdown_export/table.rb
index 35f1b58..fc212bc 100644
--- a/lib/docs_kit/markdown_export/table.rb
+++ b/lib/docs_kit/markdown_export/table.rb
@@ -14,14 +14,21 @@ def render(node)
rows = rows(node)
return "" if rows.empty?
- header, *body = rows
- lines = [row(header), separator(header.length)]
+ width = rows.map(&:length).max
+ header, *body = pad(rows, width)
+ lines = [row(header), separator(width)]
lines.concat(body.map { |cells| row(cells) })
lines.join("\n")
end
private
+ # Pad every row out to +width+ with empty cells so the header, separator,
+ # and all body rows declare the same column count (a rectangular GFM table).
+ def pad(rows, width)
+ rows.map { |cells| cells + Array.new(width - cells.length, "") }
+ end
+
# All rows as arrays of cell strings, header row first. A row leads;
# /bare rows follow.
def rows(node)
diff --git a/lib/docs_kit/registry.rb b/lib/docs_kit/registry.rb
index 1753caa..6914c0e 100644
--- a/lib/docs_kit/registry.rb
+++ b/lib/docs_kit/registry.rb
@@ -118,7 +118,9 @@ def grouped
# so the sidebar never links a page that isn't written yet. This is the
# transform every site used to hand-write in its nav lambda.
def nav_items
- all.select(&:view_class).group_by(&:group).transform_values do |items|
+ all.select { |item| item.respond_to?(:view_class) && item.view_class }
+ .group_by { |item| item.public_send(group_by_attribute) }
+ .transform_values do |items|
items.map { |item| DocsKit::NavItem.new(href: item.href, label: item.title, icon: item.icon) }
end
end
diff --git a/lib/docs_kit/search_index.rb b/lib/docs_kit/search_index.rb
index a765097..b34621a 100644
--- a/lib/docs_kit/search_index.rb
+++ b/lib/docs_kit/search_index.rb
@@ -97,11 +97,25 @@ def build_entry(page_title, section_title, href, body)
end
# → [intro_text, [[heading, body], ...]]. Splits on lines that are exactly a
- # level-2 ATX heading (`## Foo`), matching MarkdownExport's twin output.
+ # level-2 ATX heading (`## Foo`), matching MarkdownExport's twin output. Scans
+ # line-by-line and toggles an in-fence flag on ``` / ~~~ fences so a `## `
+ # inside a code block stays body text — the rendered page never ids it, so a
+ # section entry there would carry a dead anchor.
def split_sections(markdown)
- parts = markdown.split(/^\#\#[ \t]+(.+?)[ \t]*$/)
- intro = parts.shift.to_s
- sections = parts.each_slice(2).map { |heading, body| [heading.to_s.strip, body.to_s] }
+ intro = +""
+ sections = []
+ in_fence = false
+ markdown.each_line do |line|
+ in_fence = !in_fence if line.match?(/^[ \t]*(```|~~~)/)
+ heading = line.match(/^\#\#[ \t]+(.+?)[ \t]*$/) unless in_fence
+ if heading
+ sections << [heading[1].strip, +""]
+ elsif sections.empty?
+ intro << line
+ else
+ sections.last[1] << line
+ end
+ end
[intro, sections]
end
diff --git a/lib/docs_kit/shortcut.rb b/lib/docs_kit/shortcut.rb
index c813a32..4d33dd7 100644
--- a/lib/docs_kit/shortcut.rb
+++ b/lib/docs_kit/shortcut.rb
@@ -70,7 +70,7 @@ def meta? = @mods.include?(:meta)
# "Ctrl K"); a BARE key is shown exactly as authored ("/", "s"). A named key
# (e.g. "escape") is left as-is either way.
def label
- mods = LABEL_ORDER.select { |flag| @mods.include?(flag) }.map { |flag| MODIFIER_LABELS[flag] }
+ mods = LABEL_ORDER.select { |flag| @mods.include?(flag) }.map { |flag| MODIFIER_LABELS[flag] }.uniq
(mods << key_label(chord: !mods.empty?)).join(" ")
end
diff --git a/lib/generators/docs_kit/install/install_generator.rb b/lib/generators/docs_kit/install/install_generator.rb
index 716d59c..f3272db 100644
--- a/lib/generators/docs_kit/install/install_generator.rb
+++ b/lib/generators/docs_kit/install/install_generator.rb
@@ -218,7 +218,18 @@ def register_stimulus_controller
inject_into_file index, after: /eagerLoadControllersFrom\([^\n]*\n/ do
"#{REGISTER_LINE}\n"
end
- append_to_file(index, "\n#{REGISTER_LINE}\n") unless stimulus_registered?(index)
+ return if stimulus_registered?(index) # inject handled it
+
+ # No eager anchor to inject after: only append the eager line if the file
+ # actually imports eagerLoadControllersFrom — appending it to a lazy-only
+ # index.js writes a call with no import, a ReferenceError that aborts the
+ # module and registers ZERO controllers (the failure REGISTER_LINE warns
+ # of). A lazy-only file is valid, so warn instead of breaking it.
+ unless File.read(index).match?(/import\s*\{[^}]*eagerLoadControllersFrom/)
+ return say_status(:skip, "#{relative(index)} doesn't eager-load — add: #{REGISTER_LINE}", :yellow)
+ end
+
+ append_to_file(index, "\n#{REGISTER_LINE}\n")
end
# Detect + print manual drift the generator can't safely automate (a
diff --git a/lib/generators/docs_kit/page/page_generator.rb b/lib/generators/docs_kit/page/page_generator.rb
index e4ae8fe..963ad74 100644
--- a/lib/generators/docs_kit/page/page_generator.rb
+++ b/lib/generators/docs_kit/page/page_generator.rb
@@ -90,8 +90,8 @@ def registry_line
# The explicit slug:/view: keywords, present only when overridden.
def override_kwargs
kwargs = []
- kwargs << %(slug: #{slug.inspect}) if options[:slug].present?
- kwargs << %(view: #{view_name.inspect}) if options[:view].present?
+ kwargs << %(slug: #{slug.inspect}) if slug != title.parameterize
+ kwargs << %(view: #{view_name.inspect}) if view_name != title.parameterize(separator: "_").camelize
kwargs
end
diff --git a/spec/docs_kit/api_client_spec.rb b/spec/docs_kit/api_client_spec.rb
index b369fe1..beccbe6 100644
--- a/spec/docs_kit/api_client_spec.rb
+++ b/spec/docs_kit/api_client_spec.rb
@@ -78,6 +78,11 @@ def render_default(token, **request_overrides)
expect(without_body).not_to include("body: JSON.stringify(")
end
+ it "javascript inlines a non-JSON String body verbatim instead of raising" do
+ out = render_default(:javascript, method: :post, body: "name=Acme")
+ expect(out).to include("body: JSON.stringify(name=Acme)")
+ end
+
it "ruby emits a Net::HTTP snippet, with a request body only when present" do
with_body = render_default(:ruby, method: :post, body: { name: "Acme" })
expect(with_body).to include("Net::HTTP")
diff --git a/spec/docs_kit/configuration_spec.rb b/spec/docs_kit/configuration_spec.rb
index bed6f3b..98919ab 100644
--- a/spec/docs_kit/configuration_spec.rb
+++ b/spec/docs_kit/configuration_spec.rb
@@ -179,6 +179,46 @@
expect(DocsKit.configuration.code_theme_dark_class).to eq(Rouge::Themes::Monokai)
end
+
+ it "degrades to nil (no dark CSS) when the theme name doesn't resolve, rather than raising" do
+ DocsKit.configure { |c| c.code_theme_dark = "Rouge::Themes::Nope" }
+
+ expect { DocsKit.configuration.code_theme_dark_class }.not_to raise_error
+ expect(DocsKit.configuration.code_theme_dark_class).to be_nil
+ end
+ end
+
+ describe "#code_theme_class" do
+ it "resolves a String theme name to the Rouge theme class" do
+ DocsKit.configure { |c| c.code_theme = "Rouge::Themes::Github" }
+
+ expect(DocsKit.configuration.code_theme_class).to eq(Rouge::Themes::Github)
+ end
+
+ it "degrades to the default theme when a typo'd theme name doesn't resolve (not a crash)" do
+ DocsKit.configure { |c| c.code_theme = "Rouge::Themes::Doesnotexist" }
+
+ expect { DocsKit.configuration.code_theme_class }.not_to raise_error
+ expect(DocsKit.configuration.code_theme_class).to eq(Rouge::Themes::Monokai)
+ end
+ end
+
+ describe "#version_badge_text" do
+ it "returns nil when unset" do
+ expect(described_class.new.version_badge_text).to be_nil
+ end
+
+ it "calls a lambda value" do
+ DocsKit.configure { |c| c.version_badge = -> { "v1.2.3" } }
+
+ expect(DocsKit.configuration.version_badge_text).to eq("v1.2.3")
+ end
+
+ it "renders a plain String value (not only a callable)" do
+ DocsKit.configure { |c| c.version_badge = "v1.2" }
+
+ expect(DocsKit.configuration.version_badge_text).to eq("v1.2")
+ end
end
describe "#dark_themes" do
@@ -288,6 +328,19 @@ def self.nav_items
it "returns an empty Hash when neither nav nor nav_registries is set" do
expect(described_class.new.nav_groups).to eq({})
end
+
+ it "honors an explicitly-assigned nav that resolves to empty (not object identity)" do
+ # A site that deliberately sets an empty nav lambda must WIN over
+ # nav_registries — the 'is nav set?' test is explicit assignment, not
+ # `equal?(DEFAULT_NAV)` (any lambda is a different object).
+ reg = registry_stub
+ DocsKit.configure do |c|
+ c.nav_registries = { "Docs" => reg }
+ c.nav = -> { {} }
+ end
+
+ expect(DocsKit.configuration.nav_groups).to eq({})
+ end
end
describe "#api_base_url" do
diff --git a/spec/docs_kit/markdown_export_spec.rb b/spec/docs_kit/markdown_export_spec.rb
index b016ba6..d6c010f 100644
--- a/spec/docs_kit/markdown_export_spec.rb
+++ b/spec/docs_kit/markdown_export_spec.rb
@@ -104,6 +104,18 @@ def view_template
expect(md).to include("`inline`")
end
+ it "round-trips inline code containing a backtick through GFM" do
+ # A single-backtick fence closes at an interior backtick, corrupting the
+ # span. The fence run must be longer than the longest run inside the text
+ # (and padded when the content starts/ends with a backtick).
+ require "commonmarker"
+ md = html_to_md("run a`b now.
")
+
+ code_span = md[/`+ ?a`b ?`+/]
+ expect(code_span).not_to be_nil
+ expect(Commonmarker.to_html(code_span)).to include("a`b")
+ end
+
it "renders a link as [text](href)" do
page = docs_content { p { a(href: "https://example.com/docs") { "the guide" } } }
@@ -158,6 +170,17 @@ def view_template
expect(md).not_to include("<")
expect(md).not_to include("&")
end
+
+ it "does not leak a Code(filename:) title into the twin as a stray line" do
+ page = docs_content { render DocsUI::Code.new("puts 1", lexer: :ruby, filename: "app.rb") }
+
+ md = to_md(page)
+
+ # The title bar is chrome — the fence must be bare, with no loose "app.rb"
+ # paragraph above it.
+ expect(md).to eq("```ruby\nputs 1\n```")
+ expect(md).not_to include("app.rb")
+ end
end
describe "callouts" do
@@ -177,6 +200,15 @@ def view_template
expect(note).to include("> **Note:**")
expect(warn).to include("> **Warning:**")
end
+
+ it "uses the author's title as the label and never fuses it into the body" do
+ page = docs_content { render DocsUI::Callout.new(:tip, title: "Heads up") { "Body here." } }
+
+ md = to_md(page)
+
+ expect(md).to include("> **Heads up:** Body here.")
+ expect(md).not_to include("Heads upBody here.")
+ end
end
describe "lists" do
@@ -240,6 +272,19 @@ def view_template
expect(md).to include("brand")
expect(md).to include("Topbar heading.")
end
+
+ it "keeps a rectangular GFM table when a body row has more cells than the header" do
+ md = html_to_md(
+ "" \
+ "| A | B |
|---|
" \
+ "| 1 | 2 | 3 |
" \
+ "
"
+ )
+
+ # Every line must declare the same number of columns as the widest row (3).
+ pipe_counts = md.each_line.map { |line| line.count("|") }
+ expect(pipe_counts.uniq).to eq([4])
+ end
end
describe "misc block elements" do
diff --git a/spec/docs_kit/registry_spec.rb b/spec/docs_kit/registry_spec.rb
index 4abd0a3..e1e8be1 100644
--- a/spec/docs_kit/registry_spec.rb
+++ b/spec/docs_kit/registry_spec.rb
@@ -71,6 +71,23 @@ def initialize(entry)
expect(klass.grouped.keys).to eq(%w[Actions])
end
+ it "builds nav_items honoring a custom group_by_attribute (no #view_class/#group required)" do
+ klass = Class.new do
+ extend DocsKit::Registry
+
+ entries [{ slug: "a", category: "Actions" }]
+ group_by_attribute :category
+ attr_reader :slug, :category
+
+ def initialize(entry)
+ @slug = entry[:slug]
+ @category = entry[:category]
+ end
+ end
+
+ expect(klass.nav_items).to eq({})
+ end
+
# ---------------------------------------------------------------------------
# Registry v2: the one-line `page` DSL. A site declares pages with a single
# line; slug/view derive from the title (both overridable), instances get the
diff --git a/spec/docs_kit/search_index_spec.rb b/spec/docs_kit/search_index_spec.rb
index d7c918f..24ea917 100644
--- a/spec/docs_kit/search_index_spec.rb
+++ b/spec/docs_kit/search_index_spec.rb
@@ -179,6 +179,24 @@
expect(hit.href).to eq("/docs/empty")
end
+ it "treats a `## ` line inside a fenced code block as body, not a section" do
+ # The bash fence contains `## install the gem`; it must NOT become a phantom
+ # section entry with a `#install-the-gem` anchor (a slug the rendered page
+ # never stamps — DocsUI::Section only ids real headings). Only the real
+ # `## Real Section` heading below the fence is a section.
+ corpus = [["Guide", "/guide", "Intro.\n\n```bash\n## install the gem\n```\n\n## Real Section\n\nBody.\n"]]
+ index = described_class.new(corpus)
+
+ # No entry carries the in-fence text as its section title / anchor.
+ fence = index.entries.find { |e| e.section_title == "install the gem" }
+ expect(fence).to be_nil
+ expect(index.entries.map(&:href)).not_to include("/guide#install-the-gem")
+
+ # The in-fence text stays with the intro, and only the real heading is a section.
+ section_titles = index.entries.map(&:section_title)
+ expect(section_titles).to contain_exactly(nil, "Real Section")
+ end
+
it "snippets from the head when the match is a section-title, not body text" do
corpus = [["P", "/docs/p", "Intro.\n\n## Widgets\n\n"]]
# 'widgets' matches the heading; the section body is empty, so the snippet
diff --git a/spec/docs_kit/shortcut_spec.rb b/spec/docs_kit/shortcut_spec.rb
index e5e86fe..3c1bed2 100644
--- a/spec/docs_kit/shortcut_spec.rb
+++ b/spec/docs_kit/shortcut_spec.rb
@@ -79,6 +79,11 @@
it "spells out explicit modifiers in order" do
expect(described_class.parse("ctrl+shift+f").label).to eq("Ctrl Shift F")
end
+
+ it "de-duplicates a label that maps two flags to the same text (mod+ctrl → one Ctrl)" do
+ # :mod and :ctrl both render as "Ctrl"; the badge must not read "Ctrl Ctrl K".
+ expect(described_class.parse("mod+ctrl+k").label).to eq("Ctrl K")
+ end
end
describe "#to_h — the shape docs-nav matches against" do
diff --git a/spec/docs_ui/error_table_spec.rb b/spec/docs_ui/error_table_spec.rb
index 0ac5bf1..55d6b53 100644
--- a/spec/docs_ui/error_table_spec.rb
+++ b/spec/docs_ui/error_table_spec.rb
@@ -60,6 +60,26 @@ def render_error_table(...)
end
end
+ context "when a param is a blank string" do
+ it "treats it as absent — no Param column when every param is blank" do
+ html = render_error_table([{ scenario: "x", status: "422", type: "validation_error", param: "" }])
+
+ expect(html).not_to include(">Param")
+ end
+
+ it "fills the em-dash placeholder for a blank param when the column is shown" do
+ html = render_error_table(
+ [
+ { scenario: "Non-HTTPS URL", status: "422", type: "validation_error", param: "url" },
+ { scenario: "Blank param", status: "422", type: "validation_error", param: "" }
+ ]
+ )
+
+ expect(html).to include("—")
+ expect(html).not_to include(%(