Configuration

The project-specific configuration of the @PLUGIN@ plugin is done in the @PLUGIN@.config file in the refs/meta/config branch of the project.

  [web]
    indexRef = master
    indexFile = Documentation/README.md

The documentation links in the project list will link to the index
file in this reference.

For branches the `refs/heads/` prefix may be omitted, all other
refs must be fully specified.

Inherited from the parent project if not specified.

Default: `HEAD`

The documentation links in web UI will link to this file.

Inherited from the parent project if not specified.

Default: `README.md`

The global formatter configuration can be overridden per project. Child projects inherit the formatter configuration from the parent projects. Configuring any parameter for a formatter overrides the complete inherited/global formatter configuration.

If set to `*` all file extensions are handled by this formatter.

Multiple extensions may be specified for a formatter.

Overrides the [globally configured file extensions](#formatterExt)
for this formatter.

Multiple mime types may be specified for a formatter.

Overrides the [globally configured mime types](#formatterMimeType)
for this formatter.

Multiple prefixes may be specified for a formatter.

Overrides the [globally configured prefixes](#formatterPrefix)
for this formatter.

Overrides the [global configuration of `includeToc`](#formatterIncludeToc)
for this formatter.

Supported for the following formatters: `ASCIIDOCTOR`

Default: `true`

If `false` the default CSS is completely replaced by the
project-specific CSS.

Overrides the [global configuration of `inheritCss`](#formatterInheritCss)
for this formatter.

Supported for the following formatters: `ASCIIDOCTOR`, `DOCX`,
`MARKDOWN`, `ZIP`

Default: `true` (CSS is inherited)

The theme name is included into the file name when loading a CSS
file, e.g. `@PLUGIN@/markdown-<theme-name>.css` when loading
project specific CSS from the project's `refs/meta/config` branch.

Overrides the [global configuration of `cssTheme`](#formatterCssTheme)
for this formatter.

Supported for the following formatters: `ASCIIDOCTOR`, `DOCX`,
`MARKDOWN`, `ZIP`

By default not set.

If several formatters can handle a file, the formatter with the
higher priority is taken. If formatters have the same priority it
is undefined which formatter is used.

Overrides the [global configured priority](#formatterPrio) for this
formatter.

Default: `0`

For some formatters a custom CSS file for the rendering can be provided in the refs/meta/config branch of the project:

ASCIIDOCTOR: @PLUGIN@/asciidoctor.css
DOCX: @PLUGIN@/docx.css
MARKDOWN: @PLUGIN@/markdown.css
ZIP: @PLUGIN@/zip.css

If link:inheritCss[inheritCss] is set to true custom CSS files are inherited from parent projects.

The global configuration of the @PLUGIN@ plugin is done in the $site_path/etc/@PLUGIN@.config file.

The plugin contains an init step that creates the initial plugin configuration.

  [formatter "ASCIIDOCTOR"]
    ext = adoc
  [formatter "DOCX"]
    ext = docx
    ext = pptx
    ext = xlsx
  [formatte "IMAGE"]
    mimeType = image/*
  [formatter "MARKDOWN"]
    mimeType = text/x-markdown
  [formatter "PLAIN_TEXT"]
    mimeType = text/plain
  [formatter "ZIP"]
    ext = jar
    ext = war
    ext = zip

Supported formatters:

ASCIIDOCTOR
DOCX
IMAGE
MARKDOWN
PLAIN_TEXT
ZIP

If set to `*` all file extensions are handled by this formatter.

Multiple extensions may be specified for a formatter.

Can be overridden on [project-level](#ext).

Multiple mime types may be specified for a formatter.

Can be overridden on [project-level](#mimeType).

Multiple prefixes may be specified for a formatter.

Can be overridden on [project-level](#prefix).

If `false` inline HTML blocks as well as inline HTML tags are
suppressed. Both will be accepted in the input but not be contained
in the output.

When this option is changed the `xdocs-x_doc_resources` cache must
be flushed.

**WARNING:** Allowing HTML for user-provided input is a security
risk, e.g. code for XSS attacks may be contained in the HTML.

*CANNOT* be overridden on project-level.

Supported for the following formatters: `ASCIIDOCTOR`, `MARKDOWN`

Default: `false`

When a formatter is disabled the `xdocs-x_doc_resources` cache must
be flushed.

*CANNOT* be overridden on project-level.

Default: `true`

Can be overridden on [project-level](#includeToc).

Supported for the following formatters: `ASCIIDOCTOR`

Default: `true`

If `false` the default CSS is completely replaced by the
project-specific CSS.

Can be overridden on [project-level](#inheritCss).

Supported for the following formatters: `ASCIIDOCTOR`, `DOCX`,
`MARKDOWN`, `ZIP`

Default: `true` (CSS is inherited)

The theme name is included into the file name when loading a CSS
file, e.g. `<review-site>/data/@PLUGIN@/css/markdown-<theme-name>.css`

Can be overridden on [project-level](#cssTheme).

Supported for the following formatters: `ASCIIDOCTOR`, `DOCX`,
`MARKDOWN`, `ZIP`

By default not set.

If several formatters can handle a file, the formatter with the
higher priority is taken. If formatters have the same priority it
is undefined which formatter is used.

Can be overridden on [project-level](#prio).

Default: `0`

The RAW formatter is used when the `raw` URL parameter is appended
to the project documentation URL.

When this option is changed the `xdocs-x_doc_resources` cache must
be flushed.

*CANNOT* be overridden on project-level.

Default: `PLAIN_TEXT`

Gerrit administrators can override the built-in default CSS by providing CSS files in <review-site>/data/@PLUGIN@/css/:

ASCIIDOCTOR: asciidoctor.css
DOCX: docx.css
MARKDOWN: markdown.css
ZIP: zip.css