Help Plug-In

The Help plug-in provides the platform documentation and the Help viewer app. The app can be used to browse both platform and app-specific help topics.

1. Topics

Help is structured into a hierarchy of topics pointing to the documentation files. One or more topics.json files define the navigation tree:

{
    "topic": "RapidContext",
    "source": "RapidContext Platform Documentation",
    "children": [
        {
            "topic": "1. Introduction",
            "url": "doc/1_introduction.html",
            "children": [
                { "topic": "1.1 Overview", "url": "doc/1_introduction.html#overview" },
                { "topic": "1.2 Standard Setup", "url": "doc/1_introduction.html#setup" },
                { "topic": "1.3 Features", "url": "doc/1_introduction.html#features" },
                { "topic": "1.4 Concepts & Terminology", "url": "doc/1_introduction.html#concepts" }
            ]
        },
        ...
    ]
}

The topic name may contain forward slashes (/) to define a hierarchy. If the specified parent topics do not exist, they will be automatically created and merged into the navigation tree.

2. Documents

Documentation can be displayed in one of the following document formats:

HTML — Standard HTML text files. Only the <body> content is used (no additional scripts or styling).
Markdown — Files with a .md extension or a text/markdown MIME type. Automatically converted to HTML.
Plain Text — All unsupported document formats are displayed as plain text.

All formats support front-matter header for metadata. This can be used to specify a topic path (if not already specified elsewhere):

---
topic: Sub-Level/Topic Name
---

3. App Documentation

Documentation for apps can be provided in the app manifest resource list. Help documents are identified using the type as follows:

resources.#.type — Any resource with doc type (automatically detected from .md or .html extension) is added to the help navigation tree.
resources.#.topic — An optional help topic path for the document. If set, any front-matter topic metadata is ignored.

For example:

id: my-app
...
resources:
  - url: app/my-app/introduction.md
    topic: My App/Introduction
  - ...

4. Custom Help App

The Help app can be configured to display any set of documents by creating a new app manifest that reuses the HelpApp source code and specifies its own topics or documents:

id: my-help
name: My Help
description: A custom clone of the built-in help app.
className: HelpApp
resources:
  - url: app/help/**
  - url: my-help/icon.png
  - url: my-help/topics.json
  - url: my-help/introduction.md

5. Syntax Highlighting

Syntax highlighting is automatically applied to code blocks using the highlight.js library. In Markdown source files, use triple backticks with an optional language identifier:

```javascript
function hello() {
    console.log("Hello, world!");
}
```

In HTML, use a <pre><code> block with an optional language-* class:

<pre><code class="language-javascript">
function hello() {
    console.log("Hello, world!");
}
</code></pre>

6. Mermaid Charts

Diagrams and charts can be embedded using Mermaid syntax. In Markdown source files, use the mermaid language identifier for a code block:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Enjoy]
    B -- No --> D[Debug]
```

In HTML, use a <div class="mermaid"> or a <pre><code class="language-mermaid"> element to contain the Mermaid diagram definition.