Help Center

Menu

Create or edit the plugin documentation

The section covers how to document your plugin and where the various sections of the plugin documentation are sourced from within your code repository.

The plugin documentation contained in src/resources/ascii/index.adoc is built from a combination of code definitions and additional asciidoc include. You should never directly edit the contents of the index.adoc file as it will be overwritten the next time your plugin gets built.

Title and description

plugin adoc title description

  1. The title is sourced from the plugin’s human friendly name property. This can be updated by editing the return value for the getPluginName() function in PluginUtils.java.

  2. The short description is sourced from the plugin’s description property. This can be updated by editing the return value for the getPluginDescription() function in PluginUtils.java.

  3. The extended description is sourced from the src/resources/ascii/sections/detaileddescription.adoc file within the plugin source. This file can include valid asciidoc code and should be used to provide further information about the plugin.

    The extended description provide context to the purpose of the plugin. In addition to providing a description of what the plugin does, it should also include information on the problem that the plugin solves, and when the plugin should and shouldn’t be used.

Plugin documentation metadata

The following metadata fields are in the generated asciidoc documentation:

:page-description: (1)
:page-keywords: (2)
:page-content-type: Documentation|Plugins (3)
:page-hc-audience: Site builder (4)
:page-marketplace-type: Plugin (5)
:page-marketplace-subtype: (6)
:page-marketplace-version: (7)
:page-plugin-scope: (8)
:page-plugin-package: (9)
:page-plugin-id: (10)
:page-plugin-interface: (11)
:page-product-topic: (12)
:page-product-subtopic: (13)
1 The title is sourced from the plugin’s human friendly name property. This can be updated by editing the return value for the getPluginName() function in PluginUtils.java.
2 The keywords are set to the content of the src/resources/ascii/sections/keywords.adoc. This file should only include a comma-delimited list of keywords on the first line of the file. The keywords listed are used by the Help Center search. Include additional terms to associate with the page that you may not want to display - e.g. if this plugin is similar to named feature in another product you can list that feature name here.
3 The content-type is a hardcoded value for all plugins.
4 The hc-audience is sourced from the return value for the getAudience() function in PluginUtils.java.
5 The marketplace-type is a hardcoded value for all plugins.
6 The marketplace-subtype is sourced from the return value for the getMarketplaceSubtype() function in PluginUtils.java.
7 The marketplace-version is hardcoded to the version of the plugin.
8 The plugin-scope is sourced from the return value for the getPluginTarget() function in PluginUtils.java.
9 The plugin package is hardcoded to the package name of the plugin.
10 The plugin package is sourced from the return value for the getPluginId() function in PluginUtils.java.
11 The plugin interface is inferred from the return value for the getMarketplaceSubtype() function in PluginUtils.java.
12 The product-topic is sourced from the return value for the getProductTopic() function in PluginUtils.java.
13 The product-subtopic is sourced from the return value for the getProductSubtopic() function in PluginUtils.java.

Usage section

The usage section is generated and can’t be changed.

The values that are auto-filled are all read from functions in PluginUtils.java, and most of these have already been covered above.

Two separate usage sections are generated if you have a plugin that can be used with both a data source and a results page, and when this occurs each usage section gets an additional sub-heading.

Configuration section

The configuration section is made up of three parts:

plugin adoc configuration

  1. plugin configuration settings: is auto-generated from the configuration key definitions provided in PluginUtils.java. The first line of the description is sourced from the description property of the key, while subsequent lines are sourced from the longDescription property. Note that the description must not contain any formatting (as this description is also used in the administration dashboard), but the longDescription can include Asciidoc formatting.

  2. additional configuration settings: is populated with the contents of the src/resources/ascii/additionalconfigsettings.adoc file. This file should record detailed information about the plugin configuration, including additional configuration that should be set.

  3. plugin configuration files: Each of the configuration files defined in PluginUtils.java auto-generates some information here along with the contents of a corresponding src/resources/ascii/configfile_<plugin-config-file-name>.adoc file. This file must be created and contain the documentation for each configuration file that the plugin uses. The documentation should cover the configuration file format and definitions of all the fields that can be set in the file. The plugin build will fail if you have any configuration files defined in PluginUtils.java that do not have a corresponding documentation file.

Examples section

The examples section provides implementation examples of how the plugin might be configured.

The section is populated with the contents of the src/resources/ascii/examples.adoc file.

Include at least one example. Some plugins will require multiple examples.

Each example should outline a background that sets up the example, and the configuration required to achieve the goal with examples of what the configured plugin does.

See also section

The see also section provides a list of links to related pages within the documentation and on external sites. The generator will include a link to the plugins section of the documentation by default.

The section is populated with the contents of the src/resources/ascii/seealso.adoc file, which should just contain a list of bulleted links.

To link to a page in the documentation use an xref: with the path relative to https://docs.squiz.net/funnelback/docs/latest/. e.g. to link to https://docs.squiz.net/funnelback/docs/latest/develop/plugins/documentation/index.html use xref:develop/plugins/documentation/index.adoc. Note that there is no leading path or slash, and the .html has been replaced with .adoc. This will ensure the links are checked when the documentation is built.

To link to an external URL use link:<URL>, where <URL> is replaced with the full page URL. e.g. To link to http://squiz.net/example.html use link:http://squiz.net/example.html

External links should be provided only if they contain very valuable information.

e.g.

seealsolinks.adoc
* xref:build/data-sources/indexer-configuration/metadata/index.adoc[]
* xref:build/results-pages/faceted-navigation/index.adoc[Faceted navigation]
* link:http://example.com[Example web link]

Change log

The change log section should be provided for all releases of the plugin after the initial 1.0.0 release (it is not required for the 1.0.0 release).

The section is populated with the contents of the src/resources/ascii/changelog.adoc file.

A change log needs to be maintained that outlines changes between different released plugin versions, and provide instructions for any steps that are required to upgrade from the previous version.

The change log should follow the following format (based on the Keep a changelog structure - see https://keepachangelog.com/en/1.0.0/)

Group changes for each version under a === vx.x.x heading, with the newest version appearing first. e.g.

=== v3.5.0

Itemize your changes under the following (level 4) headings, with each item listed as a separate (unordered) list item:

  • Added …​

  • Changed …​

  • Deprecated …​ (for soon-to-be-removed items)

  • Removed …​ (for items that are now removed)

  • Fixed …​

e.g.

changelog.adoc
== Change log

=== v2.0.0

==== Added

* A configuration file, `plugin.example-advanced-config.cfg` to enable advanced rule configuration for the plugin.

=== v1.0.1

==== Added

* A configuration option, `plugin.example.sort-order`, to enable the sort order to be set.

==== Fixed

* An issue with the processing of document titles.
* An issue with the default sort order.