User Guide

The @PLUGIN@ plugin serves project documentation as HTML pages. Project documentation can be written in different syntaxes, e.g. as Markdown or Asciidoc.

By default the entry point to the project documentation is a README.md file in the root directory of a project. Another index file may be configured.

If a project contains the index file in its root directory then a link to the project documentation is displayed for it in the project list.

Clicking on the documentation icon opens the rendered HTML of the index file in a new tab.

If a project is selected the project documentation is also available from the Projects menu.

The documentation is served from the tip of the default branch. The documentation for other branches is available from the project branches screen.

When reviewing documentation changes a preview of the rendered HTML is available for project documentation files. This allows to detect any formatting issues quickly. The preview is available from the side-by-side diff view and it is opened in a new tab.

The URL scheme of the plugin allows to access the HTML of all project documentation files in the project from any revision (branch or commit). The project name and the revision must be URL encoded.

  /@PLUGIN@/project/<project>/rev/<revision>/<file>

E.g.:

  /@PLUGIN@/project/dev%2Ftools%2Fcode-checks/rev/stable-1.3/docs/faq.md

A project documentation file can contain links to other project documentation files which are contained in the project.

  The installation is described in the [installation guide](install-guide.md).

Images that are stored in the project can be included into the project documentation, but they are only rendered if the image mimetype is configured on the Gerrit server as a safe mimetype.

  ![Screenshot](images/screenshot.png)

By default inline HTML blocks as well as inline HTML tags may be suppressed by formatters. If suppressed both will be accepted in the input but not be contained in the output.

Project documentation files may include the following macros which are automatically replaced when the HTML pages are generated.

• \@URL@: The web URL of the Gerrit server.
• \@PROJECT@: The name of the project from which the documentation is shown.
• \@PROJECT_URL@: The web URL of the project from which the documentation is shown.
• \@REVISION@: The abbreviated ID of the revision from which the documentation is shown.
• \@GIT_DESCRIPTION@: The output of git describe on the revision from which the documentation is shown, or the abbreviated ID of the revision if no names are found.

The plugin provides several formatters for different project documentation syntaxes. The formatters can be configured on project level and for some formatters the CSS can be customized.