Otter Wiki Documentation

An Otter Wiki is a Python-based collaborative content management system (wiki) built with the Flask microframework. It uses a Git repository to store and track all content changes.

Key features include:

• Markdown Support: Uses Markdown for markup, including extended syntax like tables, footnotes, fancy blocks, alerts, and mermaid diagrams.
• Editor: Powered by CodeMirror with markdown highlighting.
• Customizable Sidebar: Supports both a Menu and/or a Page Index.
• Version Control: Full changelog and page history via Git.
• User Management: User authentication and admin settings.
• Attachments: Support for page attachments.
• Interface: Minimalistic design with dark-mode support, using the Halfmoon CSS framework and Font Awesome icons.

An Otter Wiki uses the pluggy framework to provide function hooks. These hooks allow developers to add or modify features via plugins.

Note: The plugin API is currently experimental and limited. If a required hook is missing, you should open an issue on GitHub.

To ensure wiki data is preserved across deployments, the chart uses Kubernetes Persistent Volume Claims (PVCs).

In the redimp/otterwiki image, wiki data is stored at the /app-data path inside the container. You can configure the storage via the following parameters:

• persistence.enabled: Set to true to enable PVC.
• persistence.storageClass: Specify the PVC Storage Class.
• persistence.accessMode: Specify the PVC Access Mode (e.g., ReadWriteOnce).
• persistence.size: Specify the storage request (e.g., 512Mi).

Application-level settings are managed through the config parameter in the Helm chart. The keys provided in the config mapping correspond to the environment variable names used in the application's settings.cfg.

Values provided via config are stored in a Kubernetes ConfigMap or, if they are considered sensitive, in a Kubernetes Secret.

Page Index

Access the A-Z page index via the A-Z button in the left sidebar. Pages are sorted by name and grouped by their first letter. You can toggle the display of page headings using the Toggle page headings switch at the top of the index.

Subdirectories

You can organize pages into subdirectories by using a slash in the name: Subdirectory/Page.

• Subdirectories act as containers and have their own independent Page index.
• Subdirectories can be nested (depth is limited only by the file system/git).

The search engine scans the content of all pages in the most recent commit. Results are ranked by hit count, with matching page names prioritized.

Search Features

• Case Sensitivity: By default, search is case-insensitive. You can enable Match case via the checkbox.
• Regular Expressions: You can perform complex searches by enabling the Regular expression checkbox. For case-sensitive regex, enable both Match case and Regular expression.

Example plugins are tested using pytest. If you are developing a new example plugin, you can use the example_plugin_loader fixture (defined in conftest.py) to load the plugin directly from its directory without needing a formal installation.

To add tests for a new plugin:

1. Create a test_<name>.py file next to existing tests.
2. Use example_plugin_loader("plugin_<name>") to load the plugin.
3. If the plugin implements a setup() hook, call it on the loaded instance.

To run the example plugin tests standalone, use the following command:

OTTERWIKI_SETTINGS="" venv/bin/pytest docs/plugin_examples/tests

Renaming

Use the Rename option in the ellipsis menu. Page names follow the same sanitization rules as creation. Note: All attachments associated with the page will be moved automatically to the new location.

Deleting

Use the Delete option in the ellipsis menu. This removes the page and all its attachments. Note: Deletions can be reverted; the system retains the data in the underlying repository.

Editing

To edit an existing page, use the edit button (pencil icon) at the top right. If the button is missing, you lack permissions, but you can still view the source code via the View Source option in the ellipsis menu.

Creating

1. Click the Create page button.
2. Enter a name for the page. You can use paths to organize structure (e.g., Subdirectory/Page).
3. Sanitization: The system automatically removes ?$.#\ and trailing slashes / from page names.
4. Submit the form to open the page in the editor.

Committing Changes

After editing, you can preview changes using the preview button. To save, click the Save button, which opens a modal requiring a commit message. To discard changes, use the close/discard button to return to the page view.

Adjust how content is handled and accessed:

• Commit Messages: By default, users must provide a message when updating a page. Set this to optional to allow empty messages.
• Page case name: By default, pages are stored as lowercase files. Check Retain page name case to preserve the original casing in the filesystem.
• Enable Git Server: When enabled, users with READ permission can clone/pull via git, and users with UPLOAD or attachment management permissions can push. Access uses HTTP Basic authentication. Users can find their clone URL in their personal settings.

To remove a plugin:

• Virtual Environment: Run pip uninstall <plugin-name>.
• Docker: Remove the plugin files from the mounted directory and recreate the container to ensure a clean environment.