Plugin Documentation

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.

You can use the running local farm to edit documentation by linking it to a new plot. Following our example, visit frame.localtest.me to create a new wiki.

Then replace the currently empty `pages` folder with a symlink as follows:

cd wiki-tls docker-compose exec farm bash # now inside the farm's container cd .wiki/frame.localtest.me rm -rf pages ln -s ~/fedwiki/wiki-plugin-frame/pages . exit

Once the symlink is in place, visit the about page and edit as you would any wiki page. About Frame Plugin

Modified plugin pages should be checked in to source control along with code changes to the plugin.

.

Note to self 2020-07-18 — same trick but for k8s based wiki.

# enter a shell in the running wiki container kubectl exec -it $(kubectl get pods -l app=wiki \ -o jsonpath='{.items[0].metadata.name}') -- sh

# now inside the farm's container cd .wiki/frame.localtest.me rm -rf pages ln -s ~/fedwiki/wiki-plugin/frame/pages . exit

Once the symlink is in place, visit the about page and edit as you would any wiki page. About Frame Plugin