Lead with Markdown in the site and plugin documentation guides - #1633
Open
slachiewicz wants to merge 3 commits into
Open
Lead with Markdown in the site and plugin documentation guides#1633slachiewicz wants to merge 3 commits into
slachiewicz wants to merge 3 commits into
Conversation
Kept as its own commit so that git log --follow and git blame still reach each page's history once the content changes.
Six guides and the fragment one of them parses. Four keep their .vm suffix because
they interpolate a version or a path; guides/index.md.vm and guides/mini/index.md.vm
keep theirs for the #set and #parse directives that build the mini-guide list.
Three things the conversion needed by hand:
* Velocity reads ## as a line comment, so level two headings use a setext underline
and deeper ones are wrapped in an unparsed block.
* APT writes $\{foo\} for a reference it means to display, and its parser strips
the backslashes, so the converted page carried a live ${prefix}, ${groupId},
${user.home} and friends. Those are now ${esc.d}{foo}.
* mini/index.txt is parsed into a Markdown page, so its APT comments and link
syntax had to become Markdown too, and it moves with the page that parses it.
Verified by building the site before and after and comparing all 265 generated
pages: 264 are identical in title, author and date metadata, visible text and every
link target. The one difference is that a Markdown table must have a header row
where the APT table had none, so two tables in the Java plugin guide gain an empty
one.
The site guide listed apt first and described it as the format 'like this one', which stopped being true when that guide became Markdown. It now lists markdown first, says plainly that new documentation should use it, and describes apt as a format that predates Maven's Markdown support - still supported, but the Maven project has moved its own documentation off it - with a pointer to doxia-converter. The plugin documentation guide gave a full APT template for src/site/apt/index.apt, so a plugin author following it started in APT. It now shows the same page as src/site/markdown/index.md, and explains the front matter and the ## trap for anyone whose page needs Velocity. The sample is wrapped in an unparsed block: the guide is itself a Velocity template, and without it Velocity reads the sample's own ## headings as line comments and deletes them - which it did, until the built page was checked.
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.
Sits on top of #1632 — the first two commits here are that PR, since the plugin documentation guide has to be Markdown before its content can be rewritten. Review the last commit only; once #1632 merges this will rebase down to two files.
Two pieces of normative guidance still point new documentation at APT:
guides/mini/guide-site.mdlistsaptfirst and calls it the format "like this one" — which stopped being true when that guide itself became Markdown. It now listsmarkdownfirst, says plainly that new documentation should use it, and describes APT as a format that predates Maven's Markdown support: still supported, but the Maven project has moved its own documentation off it. Adds a pointer todoxia-converterfor anyone converting an existing page.guides/development/guide-plugin-documentationis the canonical instruction for documenting a plugin, and it gave a full APT template forsrc/site/apt/index.apt— so an author following it started in APT. It now shows the same page assrc/site/markdown/index.md, with the YAML front matter that carries the title, author and date, plus a note about naming the fileindex.md.vmand keeping headings away from##if the page needs Velocity.One thing worth seeing: that guide is itself a Velocity template, and Velocity reads
##as a line comment even inside a fenced code block. The first version of this change silently lost## Goals Overviewand## Usagefrom the rendered sample. It is now wrapped in#[[ ]]#. That only showed up because the built page was checked rather than the source.Verified by building the site: the sample renders all its headings and no
#[[markup leaks into the page.