Plugin Wiki Pages

This page describes hosting of plugin documentation on the Jenkins wiki. For newly created plugins it is recommended to keep plugin documentation in GitHub repositories. See this page for the guidelines.

Plugins should have user documentation outside the plugin itself so that potential users can learn about the plugin without installing it. A common way to do this is to create a plugin wiki page on the Jenkins wiki.

Creating a wiki page

Plugin wiki pages should be organized as child pages of the Plugins page. Go to that page, be sure to be logged in, and click Create in the page header. The page you’ll create will automatically be added as a child of the Plugins page.

Content recommendations

Plugin macro

Use the {jenkins-plugin-info:pluginId=YOUR-ARTIFACT-ID} macro near the top of your plugin’s wiki page. It will link to the plugin’s page on the plugin site, as well as any security warnings applicable to the plugin to warn users.[1]

Documentation

The wiki page should contain basic documentation that explains what the plugin does, and how to configure it in Jenkins. This documentation should be kept up to date as the plugin changes. Note that it is best to keep the documentation as a whole in mind when amending it: For example, don’t just add new sections at the bottom when you add new features, but write the documentation so that someone new to the plugin has the best experience reading the documentation.

Changelog

Include a changelog that shows the changes in every version you release. Keep in mind that many Jenkins users are not necessarily Java developers, so focus on the effect of a change to users, rather than exactly what code you changed. People can always read the source code if they want to know exactly what was changed.

Basic macros only

If a plugin links to its wiki page from its metadata (defined using the <url> tag in the pom.xml), the plugin site will scrape the wiki and include the page contents directly. If a non-wiki URL is specified, for example to a GitHub repository, it will only show a link instead.

Given the limitations inherent in including scraped content, many advanced macros will not show up properly on the plugin site: Basically every macro that uses AJAX to load data in the background will not work. Since Jenkins will link to the plugin’s page on the plugin site from its plugin manager, this will result in a bad experience reading broken documentation for many users.

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 ID you want to export 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 myplugin.md --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 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

  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. Once the pull request is merged, replace the content on Wiki by a link to the new GitHub location (use info boxes to do that).


1. Before the plugin site existed, the wiki macro included various statistics, but that was removed as redundant.

References