Generate docs from Markdown with Pandoc #3186
Open
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.
This PR changes the format of the user manual from YAML to Markdown.
This gives a multitude of benefits, including better editor support, smaller files, better tooling, and more flexible document structure.
The idea is that manuals for old jq versions (1.3 to 1.7) remain untouched as YAML, whereas new documentation is written in Markdown (
docs/content/manual/manual.md
). When new features are added to jq, they can be documented in the manual with a compatibility note, which should allow to document all future jq versions in one file.I've tried to preserve the look as much as possible, but there are still a few aesthetic differences compared to the current manual, especially concerning the styling of examples. If these are important to you, I can try to make them more similar.
A preview of the current state:
What works:
man.test
,manonig.test
)What does not work:
./configure --enable-docs
even if you have all required dependencies (i.e. Pandoc).