Plugins contain documentation pages that describe capabilities, explain specialized markup, and include examples of usefully configured examples.
Operation
The wiki server will serve these pages when requested by name. A page titled About {type} Plugin provides an overview of available pages where {type} is the capitalized type name for the plugin.
Plugin pages are typically titled with wordy variations, like More About {type} Plugin, so as to avoid conflicts with other content in the wiki.
The server may annotate the plugin's pages with a "plugin" field identifying where it was found. The hover text of the page's flag will show this information.
{ "title": "About Method Plugin", "story": [ ... ], "journal": [ ... ], "plugin": "method" }
The client may render a plugin's page distinctly based on the existence of the "plugin" field. Currently a green fade border indicates plugin sourced pages.
Convention
Plugin pages are expected to provide specific content not readily available by other means.
A page should describe the plugin's purpose.
A page should provide an instantiated example.
A page should link to the source code for the plugin.
A page should document the markup it interprets.
Authoring
It is most convenient to author plugin pages with wiki itself. There are several strategies to do this.
You can use the npm wiki to edit documentation by serving it from your plugin's directory.
cd wiki-plugin-calendar wiki -p 3010 -d . --security_legacy
Or, if it is important to have the new plugin installed while editing, try launching a development copy directed at the plugin for pages.
P=`pwd` (cd ../wiki; node index.js -p 3010 -d $P --security_legacy)
A good strategy is to hard link the page between the local clone of a plugin repository and the flat file pages of a local wiki server.
A possible strategy is to edit the plugin page directly and expect it to be saved in local flat files where it can be moved back into the plugin when editing is complete. Note: this sounds simpler but becomes tedious and has been known to go wrong.
A dangerous strategy is to edit the page json with a text editor. It is easy to create page content that cannot be recreated from the journal. It is also easy to create illegally formatted json leading to inexplicable failures in the client.
Modified plugin pages should be checked in to source control along with code changes to the plugin.