# RFD 084: Configurable Markdown Element Coloring - **Status**: Discussion - **Category**: Design - **Authors**: Jean Mertz - **Date**: 2026-05-12 - **Extends**: [RFD 004] ## Summary Introduce a `MarkdownStyleSheet` in `jp_md` that maps the markdown elements the terminal renderer emits (headings per level and their markers, list markers, inline code, blockquote marker, links, emphasis, strikethrough, underline, …) to a structured `Style` value, and expose it as user config under `style.markdown.elements.*`. This replaces today's hard-coded SGR escapes in the terminal renderer and the one-off `inline_code_bg` plumbing with a single coherent abstraction. ## Motivation The terminal markdown renderer in `jp_md` currently bakes every styling decision into the AST walker as fixed SGR constants from `ansi.rs`: - Headings use `BOLD_START`/`BOLD_END` regardless of level. - The `#` glyphs are emitted unstyled while the heading text is bold; there is no way to style the marker independently of the text. - Bullet markers (`-`, `*`) and ordered-list markers carry no styling. - Inline code can override its background (via `inline_code_bg`) but not its foreground; the only colored aspect of inline code is the theme-derived background. - Blockquote bodies pick up the syntect theme's gutter foreground, but the `>` marker can't be styled differently from the body. - Thematic breaks, links, task checkboxes, and table borders have no user-controllable styling at all. The one place we *did* add a knob — inline code background — required threading `Option<(String, String)>` through `Formatter`, `TerminalFormatter`, the table formatter, and the render-site wiring in `jp_cli::render::chat`. Adding the next knob (inline code foreground, heading-level colors, dim bullets) by the same pattern compounds the surface area linearly per attribute. Users increasingly want per-element control; doing this piecemeal produces a builder with dozens of scalar methods and a config schema that has to grow in lockstep. The renderer also has correctness work that a structured representation makes easier: `AnsiState` already tracks bold, italic, underline, strikethrough, fg, and bg across wrap breaks (see commit `b5bb5eff`). What's missing is a push/pop discipline so that multiple overlapping element styles can be unwound in order; the current code special-cases one snapshot/restore for blockquote fg. Generalizing it once (push/pop stack of element styles) costs less than open-coding the same logic per element. ## Design ### What the user sees A new `style.markdown.elements` subtree, where each leaf is a `Style` value with `fg`, `bg`, `intensity`, `italic`, `underline`, and `strikethrough`: ```toml [style.markdown.elements.heading.h1] fg = "#fb4934" intensity = "bold" [style.markdown.elements.heading.h2] fg = "#fabd2f" [style.markdown.elements.heading_marker.h1] fg = 244 intensity = "dim" [style.markdown.elements.bullet_marker] fg = "#83a598" [style.markdown.elements.ordered_marker] fg = "#83a598" intensity = "bold" [style.markdown.elements.inline_code.body] fg = "#d3869b" bg = "#3c3836" # Suppress the theme-derived blockquote-body foreground without resetting # the channel, so the surrounding context's foreground shows through. [style.markdown.elements.blockquote.body] fg = "inherit" [style.markdown.elements.blockquote.marker] fg = "#928374" intensity = "bold" # Dim the link framing characters; style label and URL separately. [style.markdown.elements.link.delimiters] intensity = "dim" ``` Every slot is optional, and every attribute within a slot is independently optional. Omitting an attribute means "no user override" — theme-derived defaults and renderer baselines still apply (see "Effective style resolution"); only when neither applies does the surrounding context show through. Use `"inherit"` on `fg` / `bg` / `intensity` to explicitly suppress those defaults and force the surrounding-context fallback. Most users will only want to set one or two attributes per slot. `intensity` accepts `"normal"`, `"bold"`, `"dim"`, or `"inherit"`. Bold and dim share a single SGR slot (SGR 1 / 2, both cleared by SGR 22), so they are modeled as four mutually-exclusive states rather than independent booleans — see "Style composition" below. `fg` and `bg` accept a color value (an ANSI 256-color index such as `244`, or a hex RGB string such as `"#3c3836"`) or one of two literal strings: `"default"` resets that channel to the terminal's own default (SGR 39 / 49); `"inherit"` suppresses theme-derived and renderer defaults *without* resetting the channel, so the surrounding context shows through. Omitting the key keeps today's behavior — theme-derived defaults apply first, then the renderer baseline, then the surrounding context. The existing `style.inline_code.background` key becomes a deprecated alias for `style.markdown.elements.inline_code.body.bg`; see Drawbacks and Phase 3. ### `jp_md` API A new `jp_md::style` module: ````rust #[derive(Debug, Clone, Default, PartialEq, Eq)] pub struct Style { pub fg: Option, pub bg: Option, pub intensity: Option, pub italic: Option, pub underline: Option, pub strikethrough: Option, } /// Intensity is a single SGR slot (bold = SGR 1, dim = SGR 2, normal = /// SGR 22). Terminals cannot render bold and dim simultaneously, so the /// values are modeled as one enum rather than independent booleans. /// /// [`Intensity::Inherit`] is an *explicit* opt-out from the renderer /// baseline (e.g. heading-bold) without committing to a specific /// intensity — the surrounding context's intensity is preserved. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Intensity { Inherit, Normal, Bold, Dim, } /// A color override for `fg` / `bg`. /// /// `Option::None` at the field level means "no override" — theme-derived /// defaults and renderer baselines still apply. The variants below are /// explicit overrides: /// /// - [`ColorOverride::Inherit`] bypasses theme / renderer defaults and /// takes the surrounding context's color. /// - [`ColorOverride::Default`] resets the channel to the terminal's /// own foreground / background (SGR 39 / 49). /// - [`ColorOverride::Color`] is an explicit color. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum ColorOverride { Inherit, Default, Color(Color), } /// Logical color: ANSI 256-color index or 24-bit RGB. Owned by `jp_md` /// so SGR escape construction stays inside the renderer crate (see /// "Effective style resolution" for the boundary rationale). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Color { Ansi256(u8), Rgb { r: u8, g: u8, b: u8 }, } #[derive(Debug, Clone, Default)] pub struct HeadingStyles { pub h1: Style, pub h2: Style, pub h3: Style, pub h4: Style, pub h5: Style, pub h6: Style, } #[derive(Debug, Clone, Default)] pub struct InlineCodeStyles { pub body: Style, // code-span literal and span background pub delim: Style, // backticks, overlays `body` } #[derive(Debug, Clone, Default)] pub struct BlockquoteStyles { pub marker: Style, // `>` glyph, including on wrapped continuation lines pub body: Style, // quote text } #[derive(Debug, Clone, Default)] pub struct TableStyles { pub border: Style, // grid characters, padding, separator rows pub header: Style, // header cell content only } #[derive(Debug, Clone, Default)] pub struct TaskCheckboxStyles { pub base: Style, // applies to both states pub checked: Style, // overlays on top when checked } #[derive(Debug, Clone, Default)] pub struct LinkStyles { pub text: Style, // visible label pub url: Style, // URL and title text pub delimiters: Style, // `[`, `](`, ` "`, `"`, `)` inline; `<`, `>` autolinks } #[derive(Debug, Clone, Default)] pub struct MarkdownStyleSheet { pub heading: HeadingStyles, pub heading_marker: HeadingStyles, pub bullet_marker: Style, pub ordered_marker: Style, pub task_checkbox: TaskCheckboxStyles, pub inline_code: InlineCodeStyles, pub code_fence: Style, // ``` glyphs and info string pub blockquote: BlockquoteStyles, pub link: LinkStyles, pub thematic_break: Style, pub strong: Style, pub emph: Style, pub underline: Style, pub strikethrough: Style, pub table: TableStyles, } ```` `MarkdownStyleSheet::default()` produces an empty override sheet — every slot is `Style::default()` and every attribute is `None`. Today's rendered output is preserved by the theme-derived and renderer-baseline defaults `jp_md` already applies; see "Effective style resolution" below. `Formatter` grows one builder method: ```rust impl Formatter { pub fn style_sheet(mut self, sheet: MarkdownStyleSheet) -> Self { ... } } ``` `Formatter::inline_code_bg` is removed; callers configure inline code background through `MarkdownStyleSheet::inline_code.body.bg` instead. The CLI helper that today reads `style.inline_code.background` is updated to bridge that field into the stylesheet so existing user config keeps working without the legacy builder (see Phase 1). ### Effective style resolution The `MarkdownStyleSheet` carries *overrides only*. `jp_md` owns the theme defaults and renderer baselines that make up today's rendering. At render time, the effective style for each element is composed in this order: 1. **Theme defaults.** Theme-derived values such as the inline-code background (`theme_bg(theme)`) and the blockquote-body foreground (`theme_blockquote_fg(theme)`). Only `jp_md` has access to the resolved `syntect::Theme`. 2. **Renderer baseline.** Hard-coded baseline attributes — headings bold, `strong` bold, `emph` italic, `strikethrough` struck, `underline` underlined — that the AST walker emits today as fixed SGR pairs. 3. **User overrides.** Values set in the `MarkdownStyleSheet` passed via `Formatter::style_sheet(...)`. `Inherit` overrides (both `ColorOverride::Inherit` and `Intensity::Inherit`) are an explicit short-circuit: they bypass steps 1 and 2 for the affected field, suppressing the theme-derived default and the renderer baseline without committing to a specific replacement. Steps 1 and 2 live entirely inside `jp_md`. `jp_cli` only constructs step 3 — a sparse override sheet from user config — and never touches the resolved theme or the renderer baseline. This keeps theme knowledge out of the crate boundary. SGR escape construction also stays inside `jp_md`. The `Color` and `ColorOverride` types above are owned by `jp_md`; `jp_cli` converts from `jp_config::types::color::Color` at the construction boundary in the shared CLI helper (see "Translation in `jp_cli`" below). `push_style` generates the SGR parameters at write time — the today-only `jp_cli` helper `color_to_bg_param` is removed. For this boundary to actually hold, the reasoning-block background path is migrated alongside: `DefaultBackground` (in `jp_md::format`) today carries a pre-built SGR parameter populated by `color_to_bg_param` in `jp_cli`. Its `param: String` field becomes a logical `Color`, and `jp_md` builds the escape internally. The user-visible `style.reasoning.background` knob keeps working unchanged; folding `reasoning` styling onto the new `Style` type itself remains a non-goal (see Non-Goals). ### Style composition Within a single rendering context, attributes compose as follows: - **`None` (key omitted) falls through defaults.** With no user override, the field picks up its theme-derived default (step 1 of effective style resolution), then the renderer baseline (step 2); if neither applies, the surrounding context is used. - **`Some(Inherit)` is an explicit opt-out from defaults.** For both `intensity` and `fg`/`bg`, `Inherit` skips steps 1 and 2 of effective style resolution for that field and takes the surrounding context's value instead. Use this when you want to suppress a theme-derived inline-code background or a renderer-baseline heading-bold without committing to a specific replacement. - **`italic` / `underline` / `strikethrough`** are independent booleans. `Some(true)` enables the attribute regardless of context; `Some(false)` disables it even if the surrounding context had it on. On `pop_style`, the prior `AnsiState` snapshot is restored. - **`intensity` is enumerated, not two booleans.** SGR has a single intensity slot: SGR 1 (bold), SGR 2 (dim/faint), SGR 22 (normal, which resets both). `Some(Intensity::Bold)` or `Some(Intensity::Dim)` set the slot; `Some(Intensity::Normal)` clears it even if the surrounding context was bold or dim. On `pop_style`, the surrounding intensity is restored — emitting SGR 1 or SGR 2 again if needed after an SGR 22 transition. - **`fg` / `bg` are innermost-wins.** `Some(ColorOverride::Color(c))` sets the channel to `c`; `Some(ColorOverride::Default)` resets the channel to the terminal default (SGR 39 / 49), overriding any theme-derived default that step 1 of resolution would otherwise apply. On `pop_style` the surrounding color is restored. This matches what the existing renderer already does via `attrs.foreground` / `attrs.background` snapshot/restore. Two worked examples: 1. Inline code (`intensity: Some(Normal)`, `fg: Some(Color(magenta))`) inside an `h1` heading (`intensity: Some(Bold)`, `fg: Some(Color(red))`): the inline code renders non-bold magenta. On exit, the heading's bold red is restored for any trailing heading text. 2. Link text (`fg: Some(Color(blue))`, no `intensity`) inside `strong` (`intensity: Some(Bold)`): the link text renders bold blue. On exit, `strong` continues bold with the surrounding (or absent) foreground restored. #### Slot overlay contract A few slots compose with each other within the same element rather than with the surrounding context. The table below pins the contract so config behavior is stable before users build themes against it. | Slot | Applies to | Overlays | | ----------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `inline_code.body` | code-span literal and span background | surrounding context | | `inline_code.delim` | opening / closing backticks | `inline_code.body` | | `task_checkbox.base` | `[ ]` / `[x]` marker (both states) | surrounding context | | `task_checkbox.checked` | the marker when checked | `task_checkbox.base` | | `blockquote.marker` | `>` glyph (including on wrapped continuation lines) | surrounding context | | `blockquote.body` | quote text | surrounding context (inline element styles overlay on top) | | `link.text` | the visible label | surrounding context | | `link.url` | URL and title text | surrounding context | | `link.delimiters` | `[`, `](`, ` " `, `"`, `)` for inline links; `<`, `>` for autolinks | surrounding context | | `table.border` | grid characters, padding, separator rows | surrounding context | | `table.header` | header cell content only | surrounding context (does not affect padding or separators, which stay under `table.border`) | | `code_fence` | ` ` \`\`\` glyphs and info string | surrounding context | ### Renderer changes `AnsiState` (`crates/jp_md/src/ansi.rs`) grows an `intensity: Intensity` field in place of its existing `bold: bool`. `restore_sequence` re-emits SGR 1 or SGR 2 as appropriate after any SGR 22 transition, so wrap-break and pop-style restoration handle dim with the same guarantees today's renderer offers for bold. This is what allows `Intensity::Dim` to be a first-class attribute rather than a layering hack. The hard-coded `write_escape(BOLD_START)` / `write_escape(BOLD_END)` pairs in `TerminalFormatter` are replaced by calls into a stylesheet-aware helper on the writer: ```rust impl TerminalWriter<'_> { pub(crate) fn push_style(&mut self, style: &Style) -> fmt::Result; pub(crate) fn pop_style(&mut self) -> fmt::Result; } ``` Internally this is a `Vec` snapshot stack. `push_style` records the current `attrs`, applies the new style on top, and emits the resulting SGR escape. `pop_style` restores the snapshot and emits whatever combination of start/end escapes (or full re-establish) is needed to transition. This generalizes the existing blockquote fg push/restore pattern. The AST walker calls into these per element: ```rust // In format_heading: let marker = self.sheet.heading_marker.for_level(level); let text = self.sheet.heading.for_level(level); self.writer.push_style(marker)?; for _ in 0..nh.level { self.writer.output("#", false)?; } self.writer.output(" ", false)?; self.writer.pop_style()?; self.writer.push_style(text)?; // ... children rendered ... // On exit: pop heading style. ``` `HeadingStyles::for_level(u8) -> &Style` is a small accessor that maps `1..=6` to the corresponding named field. Out-of-range levels (none should reach the renderer, but comrak's `NodeHeading::level` is a `u8`) fall back to `h6`. Same mechanism for `format_item` (bullet / ordered marker vs body), `format_code` (`inline_code.body` and `inline_code.delim`), `format_block_quote` (`blockquote.marker` and `blockquote.body`), etc. The wrap-break path inside `TerminalWriter` restores fg/bg across line breaks through `AnsiState`, but the prefix mechanism is a separate concern that the stylesheet exposes for the first time. `TerminalWriter::prefix` is currently a flat `String` written verbatim at the start of each continuation line — so the `>` glyph on wrapped blockquote lines would inherit body styling, not `blockquote.marker`. To honor the marker / body split, `prefix` becomes a sequence of styled spans (`Vec`, each carrying an optional `Style`). `write_prefix` walks the spans and emits `push_style` / `pop_style` around each. `format_block_quote` pushes a ` > ` span styled as `blockquote.marker`; list items push their indentation span with no style. The continuation-line styling now matches the first line by construction. ### Renderer data flow The stylesheet has to reach every code path that emits styled output, not only the AST walker. Four paths need wiring: 1. **AST walker (`format_terminal` / `format_terminal_with`).** The stylesheet is held on `TerminalFormatter`. All AST elements — headings, lists, blockquotes, inline code, strong, emphasis, underline, strikethrough, links, thematic breaks — go through `push_style` / `pop_style` against it. 2. **Streaming code fence helpers (`render_code_fence`, `render_closing_fence`, `render_code_line`).** These live outside the AST walker (`crates/jp_md/src/format.rs`, around the `Formatter::render_code_*` block) and are consumed by `jp_cli::render::chat` for live streaming. They take the stylesheet so `code_fence` styling applies identically to streamed and buffered fenced code. 3. **Table renderer (`jp_md::table::format_table`).** Tables go through a nested `TerminalFormatter` per cell (`crates/jp_md/src/table.rs`). The stylesheet is threaded through `format_table` and forwarded to each cell formatter, so `table.border`, `table.header`, and inline element styles inside cells all use the same sheet. 4. **Tool-result renderer (`jp_cli::render::tool::ToolRenderer`).** Tool call results are rendered through a separately-constructed `Formatter` (`crates/jp_cli/src/render/tool.rs`) that calls `begin_code_block` / `render_code_line` and emits its own fence markers. The same shared CLI helper that produces `ChatRenderer`'s formatter produces this one, so `code_fence` styling and syntax highlighting are identical across chat output and tool-result output. Tool-result bodies are not parsed as markdown by this RFD; inline markdown element styling (`strong`, `emph`, `link.*`, `blockquote.*`, etc.) applies to tool results only if a future change routes those bodies through `format_terminal`. The current manual ` ``` ` emission in `ToolRenderer::render_result` migrates to `render_code_fence` / `render_closing_fence` so `code_fence` styling actually applies. Without (2)–(4), schema slots like `code_fence`, `table.border`, and `table.header` would be visible in config but never reach the output, and buffered vs streamed vs tool-result rendering of the same fenced block could diverge. ### Configuration types `jp_config` gains: - `style::Style` — a `Config`-derived struct mirroring `jp_md::Style`: `fg`, `bg`, `intensity`, `italic`, `underline`, `strikethrough`, each `Option<...>`. `fg` / `bg` deserialize from either a color value (ANSI 256 number or hex string via the existing `jp_config::types::color::Color`) or one of the literal strings `"default"` / `"inherit"`, producing a `ColorOverride`. `intensity` deserializes from `"normal"` / `"bold"` / `"dim"` / `"inherit"`. - `style::markdown::HeadingStylesConfig` — a `Config`-derived struct with six named fields `h1` through `h6`, each a `Style`. Mirrors `HeadingStyles` in `jp_md`. Six fixed levels means no runtime range validation is needed; an unknown segment such as `h0`, `h7`, or `foo` is rejected by the assignment glue as a missing key. - Grouped sub-style configs mirror their `jp_md` counterparts: `InlineCodeStylesConfig` (`body`, `delim`), `BlockquoteStylesConfig` (`marker`, `body`), `TableStylesConfig` (`border`, `header`), `TaskCheckboxStylesConfig` (`base`, `checked`), and `LinkStylesConfig` (`text`, `url`, `delimiters`). Each leaf field is a `Style`. - `style::markdown::ElementsConfig` — the slot tree from `MarkdownStyleSheet`, mirrored with `Style` and grouped sub-style values; `heading` and `heading_marker` use `HeadingStylesConfig`. - `MarkdownConfig` gains an `elements: ElementsConfig` field. The shared CLI helper translates `jp_config::style::Style` values into `jp_md::Style` at the boundary — including the `Color` → `jp_md::Color` and `"default"` → `ColorOverride::Default` conversions. SGR escape generation stays inside `jp_md`. CLI assignment uses path segments per the existing `KvAssignment` convention: ```sh jp query --cfg style.markdown.elements.heading.h1.fg="#fb4934" jp query --cfg style.markdown.elements.heading.h1.intensity=bold jp query --cfg style.markdown.elements.bullet_marker.fg="#83a598" jp query --cfg style.markdown.elements.blockquote.marker.intensity=bold jp query --cfg style.markdown.elements.link.delimiters.intensity=dim ``` The usual `PartialConfigDelta`, `FillDefaults`, `AssignKeyValue`, and `ToPartial` glue follows the existing pattern (see `MarkdownConfig` and `InlineCodeConfig` today). `Style` is reusable: `tool_call`, `reasoning`, and other style sections that currently roll their own attribute bags can migrate to it as a follow-up, but that's out of scope for this RFD. ### Translation in `jp_cli` A single shared helper (today: `formatter_from_config` in `crates/jp_cli/src/render/chat.rs`, ~20 lines; lifted into a sibling module shared by both renderers) becomes the only place that maps `style.markdown.elements.*` config into a sparse `MarkdownStyleSheet` — the user-override layer, step 3 of "Effective style resolution". Both `ChatRenderer` and `ToolRenderer` construct their `Formatter` through this helper, so they receive identical stylesheets and themes. The helper does not resolve theme defaults or apply renderer baselines; those stay inside `jp_md`. The existing `inline_code_bg` branch is deleted; its logic moves into the stylesheet construction. The config-color-to-SGR translation (`crate::format::color_to_bg_param`) is also deleted: `jp_md::Color` / `ColorOverride` are passed through and `jp_md` emits the SGR. The reasoning-background path constructs `DefaultBackground` with a logical `Color` (in `ChatRenderer::terminal_options`); the SGR is built inside `jp_md`. No `jp_cli` code path constructs SGR escapes for markdown element styling or `DefaultBackground` after Phase 2 completes. Other terminal chrome owned by `jp_cli` — role headers, the reasoning-timer line, tool-call labels, progress indicators — keeps its existing styling path and is out of scope for this RFD. ## Drawbacks - **Upfront diff size.** New module in `jp_md`, refactor of ~12 call sites in `render.rs`, new config types with full schematic glue, new tests. Bigger than "add one more scalar knob." - **Stack discipline becomes a correctness invariant.** Every `push_style` needs a matching `pop_style`, including in error paths and in the comrak pre/post-order traversal. Today's symmetric `START`/`END` pairs are easier to audit visually. A debug assertion in `finish()` that the stack is empty mitigates this but doesn't eliminate it. - **Style composition becomes a user-visible contract.** The rule for omitted keys (theme default → renderer baseline → surrounding context), the explicit `Inherit` opt-out for both `intensity` and `fg` / `bg`, the four-state `intensity` semantics, and the innermost-wins / explicit-default rule for `fg` / `bg` (see "Style composition") are part of the config surface once shipped. Snapshot tests for nested cases (inline code in heading, link in strong) pin the behavior. - **Prefix becomes styled.** `TerminalWriter::prefix` changes from a flat `String` to a list of styled spans so the blockquote `>` marker can be styled independently of body content on wrapped continuation lines. The per-line cost is small (prefix length is bounded by nesting depth × a few characters), but it touches a hot path and rewrites prefix bookkeeping in `format_block_quote` / `format_item`. - **Deprecated config key.** `style.inline_code.background` becomes a deprecated alias for `style.markdown.elements.inline_code.body.bg` (see Phase 3). This RFD does not hard-break existing config files, environment variables, `--cfg` assignments, or stored conversation deltas; hard removal is deferred to a follow-up. - **Config surface gets bigger.** `style.markdown.elements.*` is roughly 30 leaf slots × 6 attributes. Most users will set none of these and rely on defaults, but the schema is visibly larger. ## Alternatives ### A. Incremental scalar knobs Add `Formatter::heading_fg(level, color)`, `Formatter::bullet_fg(color)`, `Formatter::inline_code_fg(color)`, etc., one at a time as users ask. Each with a matching `style.markdown.heading_h1_fg`-style config key. Rejected because the Cartesian product (~30 leaf slots × ~6 attributes) makes the builder unwieldy and the config schema visually noisy. Each addition touches `Formatter`, `TerminalFormatter::new`, the `Debug` impl, the config schema, the assignment glue, and the wiring in `formatter_from_config`. The piecemeal cost is acceptable for one knob; for twenty it is not. ### B. Adopt `termimad`'s `MadSkin` `termimad` already solved the "per-element terminal styling" schema problem with `MadSkin` / `LineStyle` / `CompoundStyle`. Adopting it wholesale would replace `jp_md`'s renderer. Rejected because termimad ships its own parser, its own soft-wrap, its own table renderer, and no streaming API. JP's renderer is comrak-based with ANSI-aware soft-wrap, default-background fills for reasoning blocks, OSC-8 file/copy links, and a streaming code-block API consumed by `jp_cli::render::chat`. Replacing it is a rewrite, not a refactor. Importing termimad for the `MadSkin` schema alone is poor coupling for a serde struct. The shape of `MadSkin` is, however, a useful reference for the `Style` and `MarkdownStyleSheet` design above. ### C. Map directly onto the syntect theme Reuse `syntect::highlighting::Theme` for element coloring (it already supports named scopes like `markup.heading`). Rejected because syntect themes have no mapping for "the `#` glyph vs the heading text," no "bullet marker" scope, and are oriented around tokenized source code, not block-level markdown. Mixing the two namespaces would conflate "code syntax highlighting" with "markdown element appearance" — they are independently meaningful and should stay decoupled. ## Non-Goals - **Replacing the syntect theme.** Code-block bodies continue to be styled by the syntect theme selected via `style.markdown.theme`. The stylesheet only affects markdown *element* styling (headings, lists, etc.), not the tokens inside fenced code. - **Migrating `tool_call`, `reasoning`, and friends to `Style`.** The new `Style` type is reusable, but folding existing style sections into it is a follow-up. This RFD focuses on the markdown renderer. - **Light/dark theme presets.** Out of scope. Users compose their own stylesheet; we may ship presets later but not in this RFD. - **Terminal capability detection.** The stylesheet is applied as-is. Whether the terminal actually renders 24-bit RGB, ANSI 256, italic, dim, etc. is the terminal's problem. Detection is a separate concern. - **Styling every comrak node.** Math, footnote definitions and references, wiki links, image delimiters, raw/HTML inline and block content, front matter, and escaped tags are passed through unstyled today and remain so. Slots can be added in a later RFD if a concrete need appears. ## Risks and Open Questions - **Naming bikeshed.** `style.markdown.elements` vs `style.markdown.colors` vs per-element keys hanging directly off `style.markdown.*`. The proposal picks `elements` because "colors" undersells it (we also set intensity, italic, underline, strikethrough) and because flat per-element keys would conflict with existing scalar fields (`wrap_width`, `theme`, `hr_style`). Worth confirming. - **Stack-discipline regressions.** A push without a pop would leak styling into following content. Mitigated by: debug-assert empty stack in `TerminalWriter::finish`, plus per-element snapshot tests that compare exact ANSI byte sequences (the renderer already has these for code blocks). ## Implementation Plan Three phases, each reviewable as a logical slice, shipped together so no intermediate config surface is exposed. ### Phase 1: `Style` and the writer stack (internal) - Add `jp_md::style` with `Style`, `Intensity`, `ColorOverride`, `Color`, `HeadingStyles`, `InlineCodeStyles`, `BlockquoteStyles`, `TableStyles`, `TaskCheckboxStyles`, `LinkStyles`, and `MarkdownStyleSheet` as sparse override types — every field optional, `Default` empty. - Replace `AnsiState::bold: bool` with `AnsiState::intensity: Intensity` and update `restore_sequence` / `update` to handle the SGR 22 bold / dim collision. - Restructure `TerminalWriter::prefix` from `String` to `Vec` (each span carrying an optional `Style`) so the `blockquote.marker` style reaches wrap-break continuation lines. Update `format_block_quote` and `format_item` to push styled / unstyled spans accordingly. - Implement theme-derived and renderer-baseline style resolution inside `jp_md` (see "Effective style resolution"). Existing snapshot tests must continue to pass byte-for-byte. - Add `TerminalWriter::push_style` / `pop_style` with the `Vec` snapshot stack and the debug-assert in `finish()`. - Refactor `TerminalFormatter`, the streaming code fence helpers (`render_code_fence`, `render_closing_fence`), and `table::format_table` to consult the stylesheet via `push_style` / `pop_style` instead of hard-coded `BOLD_START` / etc. - Add the `Formatter::style_sheet` builder method. - Bridge the existing `style.inline_code.background` config field into `MarkdownStyleSheet::inline_code.body.bg` inside `formatter_from_config`, so removing `Formatter::inline_code_bg` doesn't regress current user config. - Remove `Formatter::inline_code_bg`. Reviewable in isolation. No new config keys; existing `style.inline_code.background` keeps working through the `formatter_from_config` bridge. ### Phase 2: Config surface - Add `jp_config::style::Style` config struct (with the six optional attribute fields), the grouped sub-style configs (`InlineCodeStylesConfig`, `BlockquoteStylesConfig`, `TableStylesConfig`, `TaskCheckboxStylesConfig`, `LinkStylesConfig`), and `ElementsConfig`. - Wire it through `MarkdownConfig` with the standard `PartialConfigDelta` / `FillDefaults` / `AssignKeyValue` / `ToPartial` glue. - Lift `formatter_from_config` out of `jp_cli::render::chat` into a shared module reachable from both `ChatRenderer` and `ToolRenderer`, and have it also translate `style.markdown.elements.*` into the `MarkdownStyleSheet`. The Phase-1 bridge for the legacy `style.inline_code.background` key stays in place alongside. Construct `ToolRenderer`'s `Formatter` through the same helper. - Migrate `ToolRenderer::render_result` from manual ` ``` ` emission to `Formatter::render_code_fence` / `render_closing_fence` so `code_fence` styling reaches tool-result output. - Migrate `DefaultBackground` (in `jp_md::format`) from `param: String` to a logical `color: Color` field so SGR construction for the reasoning-background path lives inside `jp_md`. Update `jp_cli::render::chat::terminal_options` to pass `Color` directly. - Delete `jp_cli::format::color_to_bg_param`. The stylesheet path already routes `Color` / `ColorOverride` through `jp_md`; with `DefaultBackground` migrated, no callers remain. - Snapshot tests covering per-element rendering, plus soft-wrap tests that verify fg colors *and* the `blockquote.marker` style survive line breaks. Add a tool-result snapshot that exercises fenced-code styling. Depends on Phase 1. ### Phase 3: Deprecate `style.inline_code.background` Hard removal is out of scope for this RFD — stored conversation `base_config.json` snapshots and event deltas already contain the old key, and `jp_conversation::compat::strip_unknown_fields` strips anything not in the schema before deserializing. Removing the field would silently drop the override on load. Instead, this phase promotes the Phase-1 CLI bridge into a proper config-layer alias: - Keep `style.inline_code.background` as a first-class but deprecated schema field on `InlineCodeConfig`. It must remain in the schema so `strip_unknown_fields` does not strip it from persisted conversation data before the alias logic runs. - During the config load / `FillDefaults` pass, copy the alias value into `style.markdown.elements.inline_code.body.bg` if the new key is unset, then clear the alias. Applies uniformly to: TOML files, `--cfg style.inline_code.background=...`, `JP_CFG_STYLE_INLINE_CODE_BACKGROUND`, and stored conversation base configs / config delta events. - With the config-layer alias in place, retire the Phase-1 `formatter_from_config` bridge for `style.inline_code.background` — by the time the formatter helper runs, the value lives at the new key. - Emit a `tracing::warn!` deprecation message when the old key is observed in any of those sources, naming the replacement key. - Document the mapping in the change log: - `style.inline_code.background` → `style.markdown.elements.inline_code.body.bg` - `JP_CFG_STYLE_INLINE_CODE_BACKGROUND` → `JP_CFG_STYLE_MARKDOWN_ELEMENTS_INLINE_CODE_BODY_BG` - Update the schema snapshot to reflect the deprecation, and update the docs to point users at the new key. Hard removal of `InlineCodeConfig::background` is scheduled for a follow-up RFD or release once the alias has been in place long enough to migrate. At that point, `--cfg=NONE` (RFD 038) is the recovery path if broken config prevents JP from starting. Depends on Phase 2. ## References - [RFD 004]: original decision to maintain a custom comrak-based terminal renderer in `jp_md`. This RFD extends that renderer's styling surface. - `jp_md::render::TerminalFormatter` — the AST walker whose hard-coded SGR calls this RFD replaces. - `jp_md::ansi::AnsiState` — the existing state-tracking primitive that the proposed writer stack builds on. - `termimad`'s `MadSkin` — referenced as schema inspiration; not adopted. [RFD 004]: 004-streaming-md-parser-renderer.md