docs: add a documentation website under docs/ - #27
Merged
Conversation
The README carried the reference: the metadata tree, the JSON export and
its four filter options, all described but never shown. Those move to an
atelier website under docs/, which prints the values out of its own
render, so the pages report the format and versions that built them.
Corrects the filter placement while doing so. The README recommended
`at: post-quarto` as the modern form; Quarto expands shortcodes during
its own pass, so a filter placed after it publishes the metadata too
late and every {{< lua-env >}} renders as nothing, silently. Verified
against the example: `at: pre-quarto` and the bare `- lua-env` form both
print Pandoc 3.10, `at: post-quarto` prints nothing.
Also records that the `meta` shortcode is not a drop-in alternative: it
prints scalars, and reports `?invalid meta type` for a path such as
`lua-env.quarto.version`, which is a list.
README.md becomes a landing page and example.qmd a short starting point
to copy.
A changelog entry naming a shortcode is expanded by Quarto rather than shown when changelog.qmd is generated from it, which fails the render when the shortcode is not available to the documentation site. Picked up from the shared scaffold, where it was fixed after quarto-revealjs-comic hit exactly that.
The generated copy of this repository's own extension sat directly under docs/_extensions/, with no owner, where it read as just another installed extension. It now goes to docs/_extensions/local/<name>/, so the path says where it came from and keeps it clear of the committed dependencies. Quarto resolves an extension under any owner directory, so nothing referencing it changes.
Picked up from the shared scaffold.
Picked up from the shared scaffold.
1.9.1 keeps the widget's menu inside a docked sidebar, which is what the three rules in assets/theme.scss did here. Those rules go with it.
The export lands beside the source document, not the output, and
`at: pre-quarto` has existed since Quarto 1.4, not 1.8.21. An inline
`{{< lua-env >}}` was left unescaped and ran during the render, warning
that no variable was given; escape it and say what a late filter really
does. Fill in the author fields the scaffold left as placeholders.
The Quarto project root is docs/, so the edit and issue links were built one level up from the page they belong to and did not resolve.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Moves the reference documentation out of
README.mdand into a Quarto website underdocs/, built on theatelierproject type and published to https://m.canouil.dev/quarto-lua-env/.The examples page prints values out of the render that produced it, so the format, the Pandoc version, and the Quarto version on the page are the ones that built it.
Writing it turned up an error in the README, corrected here. The README gave
at: post-quartoas the modern way to enable the filter. Quarto expands shortcodes during its own pass, so a filter placed after that pass publishes the metadata too late and every{{< lua-env >}}renders as nothing, with no warning. Rendering the example three ways confirms it: the bare- lua-envform prints Pandoc3.10,at: pre-quartoprints3.10, andat: post-quartoprints nothing. The site, the example, and the reference all useat: pre-quarto.reference.qmdalso records that Quarto's ownmetashortcode is not an equivalent: it prints scalars and reports?invalid meta typefor a path such aslua-env.quarto.version, which is a list of three numbers.README.mdbecomes a landing page pointing at the site, andexample.qmda short standalone starting point to copy.