Skip to main content

Markdown Resources

The text/markdown MIME type renders Markdown content directly in the Symphony React component tree using react-markdown with MUI styling. Unlike other resource types, Markdown is not rendered in an iframe—it appears inline in the Symphony UI, matching the look and feel of the built-in help system.

When to Use​

Use text/markdown for:

  • Extension help and documentation pages.
  • Content that should visually integrate with the Symphony help system.
  • Pages where the focus is on structured text, not interactive functionality.

For interactive user interfaces, use text/symphony-jsx or text/html+symphony.

Registration​

Python​

import os

# Load from a file
help_path = os.path.join(os.path.dirname(__file__), 'pages', 'help.md')
with open(help_path) as f:
    help_content = f.read()

ext.add_resource("ui://my_ext/help", "text/markdown", help_content)
ext.add_route("/help/extensions/MyExtension", "ui://my_ext/help")

Java​

Resource help = new Resource()
    .uri("ui://my_ext/help")
    .mimeType(MimeType.TEXT_MARKDOWN)
    .text(getTemplate("help.md"));

Go​

ext.AddResource("ui://my_ext/help", "text/markdown", helpContent)

Frontmatter​

Markdown resources support YAML frontmatter for metadata that controls how the page is displayed in the Symphony help navigation:

---
title: My Extension
breadcrumbs:
  /: Home
  /help: Help
  /help/extensions: Extensions
  /help/extensions/my-extension: My Extension
---

# My Extension

Your extension documentation here.
FieldDescription
titleThe page title displayed in the browser tab and navigation
breadcrumbsA map of paths to labels for breadcrumb navigation

Template Variables​

Markdown content supports template variables that are substituted at render time:

VariableDescriptionExample Value
{​{name}}Full product nameCirata Symphony
{​{shortname}}Short product nameSymphony
{​{origin}}The base URL of the instancehttps://symphony.example.com
{​{address}}The NATS addressnats://symphony.example.com:4222
{​{version}}The product version1.2.3

Use these to make your documentation adapt to the deployment:

Connect to {​{name}} at `{​{address}}` using a valid API token.

Download the library from [Languages and Libraries](/help/development/languages).

Supported Markdown Features​

Headings​

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Code Blocks​

Syntax-highlighted code blocks with language identification:

```python
from cirata import symphony

async def main():
    ext = symphony.Extension("Example", "example")
    async with ext:
        await ext.operate()
```

Tables​

| Column A | Column B |
|----------|----------|
| Cell 1   | Cell 2   |

Internal links use paths relative to the help root:

[Platform Functionality](/help/development/functionality)

Images​

![Architecture Diagram](/images/help/architecture.png)

Images are styled with max-width: 600px and centered automatically.

Lists​

Both ordered and unordered lists are supported:

- First item
- Second item
  - Nested item

1. Step one
2. Step two

Help Page Convention​

Extension help pages should be routed under /help/extensions/<ExtensionName> so they appear alongside the built-in documentation:

ext.add_route("/help/extensions/MyExtension", "ui://my_ext/help")

The breadcrumbs in the frontmatter should follow the standard hierarchy:

breadcrumbs:
  /: Home
  /help: Help
  /help/extensions: Extensions
  /help/extensions/MyExtension: My Extension

Complete Example​

A help page for an extension that manages data catalogs:

---
title: Catalog Manager
breadcrumbs:
  /: Home
  /help: Help
  /help/extensions: Extensions
  /help/extensions/CatalogManager: Catalog Manager
---

# Catalog Manager

The Catalog Manager extension provides tools for browsing and managing
data catalogs connected to {​{name}}.

## Getting Started

Navigate to **Catalog Manager** in the {​{shortname}} sidebar to view
your connected catalogs. You can browse tables, view schemas, and
monitor replication status.

## Connecting a Catalog

1. Open the Catalog Manager settings page.
2. Provide the connection details for your catalog.
3. Select **Connect** to register the catalog with {​{shortname}}.

## API Access

The Catalog Manager exposes REST endpoints for programmatic access:

\```bash
curl -H "Authorization: Bearer <token>" {​{origin}}/api/v1/extensions/catalog/catalogs
\```

## Troubleshooting

If a catalog shows as disconnected, verify that the extension process
is running and that the network path between the extension and the
catalog is available.

Limitations​

  • No interactivity—Markdown pages do not support JavaScript or event handlers. For interactive UIs, use a different resource type.
  • No iframe isolation—Markdown renders in the main Symphony React tree. This is generally a benefit (consistent styling), but means custom CSS in the Markdown could affect the surrounding UI.

See Also​