Plugin Wiki Pages

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.

Migrating from Wiki to GitHub

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:

  1. Fork the plugin repository in GitHub and clone it to the local machine.

  2. Export the documentation. It can be done in a manual or automated way, see below

  3. Add the documentation and images to the repository

    • You can merge the exported file with the existing README file or create a new one.

  4. Copy-edit the documentation, see below

  5. Modify the URL documentation page reference in the project file so that it points to GitHub (documentation).

  6. Commit changes, push them to your fork and create a pull request against the repository.

Exporting Wiki documentation (automatic way)

The Jenkins Wiki Exporter can export plugin documentation to Markdown or Asciidoc.

  1. Go to the Jenkins Wiki Exporter service

  2. Specify the plugin Wiki URL or ID in the field

  3. Select the export option. For plugins with images you will need to use Markdown Zip or Asciidoc Zip

  4. Click Convert to do the conversion. It will either show the converted file or provide the archive to download

Exporting Wiki documentation (manual way)

  1. Open the plugin’s Wiki page page you want to migrate.

  2. In the "…​" button in the top right corner click the View Source action. A new window will open.

  3. Save the document as HTML to the repository, e.g. as myplugin.html.

  4. Call pandoc -o --extract-media=docs/images myplugin.html to export Markdown. Asciidoc format can be used as well, with the .adoc extension.

  5. 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.

Reviewing the documentation

  1. 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.

  2. Extract changelogs to a separate file

    • It is recommended to extract changelogs to a separate 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

  3. 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.)

  4. Commit changes, push them to your fork and create a pull request against the plugin repository

  5. Once the pull request is merged, create an INFRA Jenkins JIRA ticket to replace the content on Wiki by a link to the new locations