quarto-dev / quarto-dev/quarto-cli

Accessing the Quarto ASTs for all documents in a Quarto project

Open
#10,539 0 comments 0 reactions 1 assignee View on GitHub

@cscheid is already working on this.

Since Aug 16, 2024.

enhancement needs-design
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

See https://github.com/quarto-dev/quarto-cli/discussions/10414

Our Lua infrastructure is well-suited for processing files one at a time, and Pandoc Lua filters are naturally AST walkers.

However, there's a legitimate use case where folks might want to analyze their Quarto projects, by choosing one or more documents and simply walking it. It would be great to support it.

For example, we have quarto inspect, and one thought is that this command could provide richer information than it does right now.

Design considerations:

  • Quarto uses a custom Pandoc reader to work around a few syntax quirks, and our extended AST syntax (FloatRefTarget, Callout, Shortcode and other nodes) involves some Lua filters of our own. So we can't simply call pandoc -f markdown -t native.
  • We want the AST available in this command to exactly match what Lua filters see. However, current Quarto filters walk the AST after the engines have executed the document. In that sense, the markdown input for Quarto is "ephemeral", and it would be very bad for quarto inspect to need to render a document. It's fundamentally hard for us to provide a "walk the AST" entry point without getting engine execution involved.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.