| The Jenkins wiki was made 'read-only' in October 2019. Plugin documentation should be maintained in the GitHub repository of the plugin. See the plugin documentation guidelines for details. |
Plugin documentation is available from the Jenkins plugins site so that potential users can learn about the plugin without installing it.
Document migration can be done in a semi-automated way using the Pandoc tool for Wiki conversion to Markdown or Asciidoc. This guide shows how to do so for a common case when the documentation page is going to be sourced from the README file inside the repository’s root.
| If there is no ticket for the documentation migration created by the current plugin maintainers, make sure to create one and then discuss with the plugin maintainers. Similarly, Asciidoc/Markdown preferences should be also discussed with maintainers. |
There are the following migration steps:
Fork the plugin repository in GitHub and clone it to the local machine.
Export the documentation. It can be done in a manual or automated way, see below
Add the documentation and images to the repository
You can merge the exported file with the existing README file or create a new one.
Copy-edit the documentation, see below
Modify the URL documentation page reference in the project file so that it points to GitHub (documentation).
Commit changes, push them to your fork and create a pull request against the repository.
The Jenkins Wiki Exporter can export plugin documentation to Markdown or Asciidoc.
Go to the Jenkins Wiki Exporter service
Specify the plugin Wiki URL or ID in the field
Select the export option. For plugins with images you will need to use Markdown Zip or Asciidoc Zip
Click Convert to do the conversion. It will either show the converted file or provide the archive to download
Open the plugin’s Wiki page page you want to migrate.
In the "…" button in the top right corner click the View Source action. A new window will open.
Save the document as HTML to the repository, e.g. as myplugin.html.
Call pandoc -o myplugin.md --extract-media=docs/images myplugin.html to export Markdown.
Asciidoc format can be used as well, with the .adoc extension.
Cleanup documentation. Jenkins Wiki Exporter does some bits automatically, but you may need to apply manual updates here.
Remove the macro references in the top of the document, if any.
Review/edit the exported file formatting
If the document includes "Table of contents", remove this section in Markdown
or replace it by :toc: macros in Asciidoc (example).
If the source Wiki page includes code blocks, they will need to be manually converted. Pandoc exports them as tables.
Extract changelogs to a separate file
It is recommended to extract changelogs to a separate CHANGELOG.md file in the repository root.
It allows tools like Dependabot to read changelog summaries
Use versions as headers. Changelogs in Wiki often include release dates, but it is better to keep them in the text below the header.
Examples: EnvInject API Plugin, AWS Java SDK Plugin
Review the text
Verify formatting and spelling
Wiki pages are often outdated, and it is nice to review them before submitting (e.g. rename "slave" to "agent", "workflow" to "pipeline", "Hudson" to "Jenkins", etc.)
Commit changes, push them to your fork and create a pull request against the plugin repository
Once the pull request is merged, create an INFRA Jenkins JIRA ticket to replace the content on Wiki by a link to the new jenkins.io locations