Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Moved documentation from wiki to GitHub repo + modern Jenkins core #59

Merged
merged 2 commits into from
Nov 25, 2019

Conversation

rsandell
Copy link
Member

Following the instructions and motivations here https://jenkins.io/blog/2019/10/21/plugin-docs-on-github/

Also updated core to slightly more modern incarnation to avoid strangeness with new plugin pom version.

Comment on lines +13 to +15
:toc:
:toc-placement: preamble
:toclevels: 3
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Those elements are not rendered by Github Markdown, and won't appear on the plugin page.
But it's not breaking the page either.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Strange, the conversion guide explicitly mentioned it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

then I might be wrong, but the "rich diff" in the PR files view do not display the TOC. Also, it's adoc, not md so you must be correct.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GitHub renders the table of contents (for example, Git plugin) as does the plugins.jenkins.io site. Unfortunately, I have not found a way to have both badges at the top and a table of contents with adoc. If I insert the badges at the top, then the table of contents is not rendered. If I insert the table of contents followed by the badges, the badges are below the table of contents and much less useful.

I'm now considering if I should switch to a format more like the credentials plugin with a top-level docs README that is short and includes badges, with links to the larger topics (a self-maintained table of contents). I really like the badges and would prefer that every plugin has them visible so that users become accustomed to reading and using them.

@rsandell rsandell merged commit 43ea1da into master Nov 25, 2019
@rsandell rsandell deleted the docsmove branch November 25, 2019 09:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants