Plugin Documentation

Documentation is an important part of any Jenkins plugin. It includes user documentation (plugin pages, changelogs, user guidelines, etc.) and the contributor documentation (how to contribute, developer guidelines, etc.). This section provides an overview of these documentation types.

Plugin pages

Plugin pages are hosted on the Plugin Site. These pages are generated automatically using the metadata from the latest plugin release and an external documentation page. External documentation can be retrieved from GitHub or from the Jenkins Wiki.

We recommend storing documentation in the GitHub repository of the plugin. It allows plugin maintainers to provide the same documentation from README pages and the Jenkins plugin site, and at the same time it allows using the Documentation-as-Code techniques when the documentation is a part of the repository and hence all common practices can be applied:

  • Pull requests and reviews

  • Creating documentation in parallel with features

  • Editing docs from GitHub Web UI, with preview support

  • Versioning, documentation for previous plugin versions can be easily accessed

Using GitHub as a source of documentation

The plugin site can pull documentation from the root README pages or from other locations defined by the plugin URL (see below). Multiple formats are supported: GitHub Flavored Markdown, Asciidoc or raw text.

To publish the plugin documentation on GitHub:

  1. Create a README page and put the plugin documentation there. This page will become a landing page for the Plugin site.

    • More documentation pages can be introduced inside the repository and linked from the README, the plugin site will display both absolute and relative links

    • Images from pages will be displayed by the plugin site as well

  2. Modify your project URL to point to the GitHub repository, e.g. https://github.com/jenkinsci/your-plugin. See the guidelines for Maven and Gradle below.

  3. Release the new plugin version. Once the plugin site picks up the release (which can take up to a few hours) it will also display the documentation from GitHub.

Documentation examples:

Valid URL formats for GitHub based documentation are

https://github.com/jenkinsci/YOUR-PLUGIN

Loads README located in the root of YOUR-PLUGIN repository from the master branch

https://github.com/jenkinsci/YOUR-PLUGIN/tree/REF

Loads README located in the root of YOUR-PLUGIN repository from the tag or branch REF

https://github.com/jenkinsci/YOUR-PLUGIN/blob/REF/path/to/readme.md

Loads a Markdown or AsciiDoc file specified by path from YOUR-PLUGIN repository’s tag or branch REF.

If you use git tag for releases, you can make sure the plugin site loads a snapshot of your README relevant for the last release by setting the URL to e.g. https://github.com/jenkinsci/${project.artifactId}/tree/${project.artifactId}-${revision}.

Using GitHub topics

Plugin labels are assigned to plugin repositories by their maintainers as GitHub topics. GitHub topics that match entries from the plugin label allowlist are displayed on the plugin site. Developers are encouraged to submit pull requests to the plugin label allowlist when they detect gaps in the list.

Plugin maintainers are encouraged to apply GitHub topics to the plugins they maintain. Topics should be assigned to plugins when the plugin relationship to the label is well above average. For example, the git plugin is labeled with git and scm-connections but is not labeled with bitbucket, github, gitlab, or gitea. As another example, the configuration as code plugin allows configuration of many plugins but does not include labels for all the plugins it can configure.

Developers should not apply labels that are so broad they lose value due to overuse. For example, a plugin that adds a few Pipeline steps should generally not be labeled with pipeline. Plugins with the pipeline label should be significant contributors to the Jenkins Pipeline.

Using Jenkins Wiki as source of documentation

Jenkins Wiki became read-only in November, 2019. Requests to plugin documentation pages on the wiki now redirect to the plugins site. See this page for more information. It also include Wiki⇒GitHub migration guidelines.

Referencing the documentation page from the project file

You should link to your plugin’s documentation, whether on the wiki or elsewhere, in your plugin’s pom.xml, (using one of the valid URL formats) like this:

<project>
  ...
  <url>https://github.com/jenkinsci/your-plugin</url>
  ...
</project>

If you’re building your plugin with Gradle, you can set the URL in your build.gradle like so:

jenkinsPlugin {
  // ...
  url = 'https://github.com/jenkinsci/your-plugin'
  // ...
}

Maintainer Information

Maintainer information is listed for every plugin on the plugin site. The maintainer metadata in jenkins-infra/repository-permissions-updater is the information source about who is a maintainer (e.g. kohsuke), and information from Jira is used to show their actual name (e.g. Kohsuke Kawaguchi).

Maintainer information in the Maven POM was used in the past, but is no longer used.

Changelogs

Once you have made your first release, you should add release notes to your plugin. You have many options how to do it:

  • use GitHub Releases (possibly with the help of Release Drafter), add a link to releases page to your documentation page (recommended)

  • create a CHANGELOG file (Markdown, Asciidoc) in the repository root and link it from the documentation page

  • include the changelog content in the documentation page

Contributor documentation

For open-source plugins it is important to have contributor guidelines to attract more contributors. GitHub offers standard ways to define guidelines and to show them to contributors, including contributing guidelines, code of conduct, pull request templates, etc.

Some notes:

Table of Contents

Plugins that create their documentation in AsciiDoc may automatically generate a table of contents for the documentation. The generated table of contents includes level 2 and level 3 headings by default. The table of contents is requested by assigning the value macro to the toc variable and by inserting a reference to the toc variable at the location where the table of contents should be inserted in the page.

= Your Plugin Name
:toc: macro

[[Introduction]]
== Introduction

Some introductory text that is placed before the table of contents.

toc:[]

[[other-heading]]
== Other Heading

Text that describes more about the plugin and is placed after the table of contents.

See the Git plugin as a table of contents example.

References