Skip to content

feat(cli): add q2 get-config to print merged document config as JSON#259

Merged
cscheid merged 1 commit into
mainfrom
feature/command-get-config
Jun 3, 2026
Merged

feat(cli): add q2 get-config to print merged document config as JSON#259
cscheid merged 1 commit into
mainfrom
feature/command-get-config

Conversation

@cscheid
Copy link
Copy Markdown
Member

@cscheid cscheid commented Jun 3, 2026

Summary

Adds q2 get-config, a CLI command that returns a document's effective configuration after Quarto 2's full metadata-merge semantics — project _quarto.yml, directory _metadata.yml layers, document front matter, and format.<fmt>.* flattening — as JSON. External tools (editors, linters, build wrappers) can read resolved config without reimplementing any of Quarto's resolution rules.

Closes #256.

q2 get-config <file> [yaml-path] [--to <fmt>] [--output value|pandoc] [--strict] [--compact]
  • No path → entire merged metadata; a dot-separated path (e.g. format.html.toc, authors.0.name) selects a value; a numeric segment indexes an array.
  • Missing path → null, exit 0 (or --strict to error).
  • --to picks the format whose format.<fmt>.* block is flattened in (default html).
  • --output value renders prose (e.g. title) as a Markdown string; --output pandoc emits a self-contained, source-free Pandoc AST fragment.

How it works

The merged metadata is the ast.meta produced at the document-profile checkpoint, so the command runs only [ParseDocumentStage, MetadataMergeStage]the same MetadataMergeStage a real render uses (one merge code path, no engines/filters/rendering). This keeps get-config consistent with rendering and cheap.

Examples

$ q2 get-config report.qmd title
"Hello *world*!"

$ q2 get-config report.qmd title --output pandoc
[{"t":"Str","c":"Hello"},{"t":"Space"},{"t":"Emph","c":[{"t":"Str","c":"world"}]},{"t":"Str","c":"!"}]

$ q2 get-config report.qmd toc --to html   # true
$ q2 get-config report.qmd toc --to pdf    # false
$ q2 get-config report.qmd authors.1.name  # "Bob"

Changes

  • pampa::config_jsonConfigValue → clean JSON projection (ProseMode::{Value, Pandoc}) + dot-path navigation with array indices.
  • pampa::writersqmd::write_inlines; json::{inlines,blocks}_to_source_free_json (reuse the maintained writers, strip s/l/attrS).
  • quarto-core::get_config::merge_document_metadata — runs the parse+merge prefix and returns ast.meta + ASTContext; re-exports the projection helpers so the CLI stays within the quarto-core API.
  • quarto get-config CLI subcommand.
  • Docsdocs/guide/get-config.qmd.

Tests

  • 12 unit (pampa), 4 integration (quarto-core), 11 CLI e2e driving the real q2 binary (quarto).
  • Full workspace cargo nextest run green (9542 passed); cargo xtask verify green including the WASM/hub-client build (pampa feeds the WASM image).

Open question for review

Default --to is html, matching render's actual default (render only supports native/html today and bails otherwise). Implementing "first declared format" now would make get-config inconsistent with render; deferred until render honors it. See the plan (claude-notes/plans/2026-06-02-get-config-command.md) for the full design and decisions D1–D8.

🤖 Generated with Claude Code

`q2 get-config <file> [yaml-path]` returns a document's effective
configuration after Quarto 2's full metadata merge (_quarto.yml,
directory _metadata.yml layers, frontmatter, and format.<fmt>.*
flattening), so external tools don't have to reimplement Quarto's
metadata-resolution semantics. Closes #256.

- pampa::config_json: ConfigValue -> clean JSON projection
  (ProseMode::{Value,Pandoc}) + dot-path navigation with array indices.
- pampa writers: write_inlines (qmd) and {inlines,blocks}_to_source_free_json
  (json) reuse the maintained writers and strip source-tracking keys.
- quarto-core::get_config::merge_document_metadata runs [Parse,
  MetadataMerge] via the same MetadataMergeStage a render uses (one merge
  path) and returns ast.meta + ASTContext.
- CLI subcommand with --to / --output {value,pandoc} / --strict / --compact.
- Docs: docs/guide/get-config.qmd.

Tests: 12 unit (pampa) + 4 integration (quarto-core) + 11 CLI e2e
(quarto). Full workspace nextest green; cargo xtask verify (WASM/hub
build) green.

Plan: claude-notes/plans/2026-06-02-get-config-command.md
bd-xoaic

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@cscheid cscheid merged commit b7bd561 into main Jun 3, 2026
4 checks passed
@cscheid cscheid deleted the feature/command-get-config branch June 3, 2026 13:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New command to get configuration

1 participant