xmarkdown

VS Code extension for Markdown authoring — autocomplete and scaffolding for Mermaid and PlantUML diagrams inside Markdown fenced blocks.

Designed for developers who want to learn and write diagrams by hand, rather than paste AI-generated output they can't maintain. Every suggestion explains what the diagram type is for and when to use it.

Features

• Mermaid autocomplete inside ```mermaid fenced blocks
• PlantUML autocomplete inside ```plantuml / ```puml fenced blocks
• Insert Diagram Scaffold command — searchable picker from the command palette
• Inline documentation on every completion item (hover to read)
• Custom catalog support — override or extend templates per workspace
• No external tools, language servers, or network calls required

Out-of-Box Behavior

After install, Mermaid completions are enabled by default. After install, PlantUML completions are enabled by default.

• No manual library download required.
• Suggestions are scoped to Mermaid and PlantUML fenced blocks in Markdown.

User Manual

1. Install

Install from Marketplace or from VSIX (Extensions: Install from VSIX...).

2. Open a Markdown file

This extension only provides completions for documents with language mode Markdown.

3. Use supported fenced blocks

Mermaid fences:

```mermaid
gr

PlantUML fences:

```markdown
```plantuml
@st

Alias also supported for PlantUML:

```markdown
```puml
@st

### 4. Trigger suggestions

#### Insert Diagram Scaffold (recommended for beginners)

For a more discoverable experience, use the command palette:

1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
2. Type **xMarkdown: Insert Diagram Scaffold**
3. Browse and search the full list of Mermaid and PlantUML templates
4. Each entry shows its description and a plain-English explanation of what it's for
5. Select one — a complete fenced block is inserted at the cursor, ready to edit

#### Inline suggestions (while typing)

Suggestions also appear automatically while typing inside supported fences.

If they do not appear automatically, trigger manually:
- Windows/Linux: `Ctrl+Space`
- macOS: `Cmd+Space` (or your configured Suggest trigger)

Current trigger characters include: `@`, `g`, `s`, `c`, `f`, `p`.

### 5. Expected behavior

- Suggestions appear only inside Mermaid/PlantUML fenced blocks.
- Suggestions do not appear in normal Markdown prose.
- Suggestions are conservative near fence boundaries.

### 6. Built-in default templates (embedded)
### 5. Inline completion documentation

When the IntelliSense list is open, hover over any suggestion (or press the `ℹ` icon) to read a plain-English explanation of what that diagram type is for, when to use it, and key syntax tips.

### 6. Built-in default templates

The extension package includes embedded default templates for both languages.

Mermaid examples:
- `graph`
- `flowchart-template`
- `sequenceDiagram`
- `sequence-template`
- `classDiagram`
- `class-template`
- `state-template`
- `erDiagram`
- `gantt`
- `mindmap`
- `journey`

PlantUML examples:
- `@startuml`
- `sequence-diagram-template`
- `class-diagram-template`
- `activity-diagram-template`
- `sequence-template`
- `class-template`
- `activity-template`
- `usecase-template`
- `@startmindmap`
- `skinparam`
- `title`

Some PlantUML defaults are adapted from https://github.com/phxql/plantuml-templates (Apache-2.0).
See THIRD_PARTY_NOTICES.md for attribution details.

## Settings

The extension contributes the following settings:

- `xmarkdown.enable`: global feature toggle. Default `true`.
- `xmarkdown.enableMermaidCompletions`: Mermaid completion toggle. Default `true`.
- `xmarkdown.mermaidPreferSnippets`: prefer snippet insertion for Mermaid templates. Default `true`.
- `xmarkdown.enablePlantUmlCompletions`: PlantUML completion toggle. Default `true`.
- `xmarkdown.plantUmlPreferSnippets`: prefer snippet insertion for PlantUML templates. Default `true`.
- `xmarkdown.enableCustomCatalog`: enable loading additional/override entries from a workspace file. Default `false`.
- `xmarkdown.customCatalogPath`: workspace-relative JSON path for custom catalog. Default `.xmarkdown/catalog.json`.

Recommended baseline if suggestions do not appear:
- `xmarkdown.enable = true`
- `xmarkdown.enableMermaidCompletions = true`
- `xmarkdown.enablePlantUmlCompletions = true`

## Custom Catalog (Flexible Library Updates)

You can add or override Mermaid and PlantUML completion entries without changing extension code.

1. Enable `xmarkdown.enableCustomCatalog`.
2. Create the file at `xmarkdown.customCatalogPath` (default `.xmarkdown/catalog.json`).
3. Add JSON in this format:

```json
{
	"mermaid": [
		{
			"label": "graph",
			"insertText": "graph LR",
			"detail": "Override default graph snippet",
			"isSnippet": true
		}
	],
	"plantuml": [
		{
			"label": "@startuml",
			"insertText": "@startuml\nAlice -> Bob: Hi\n@enduml",
			"detail": "Override start block",
			"isSnippet": true
		}
	]
}

Notes:

• Matching labels are replaced case-insensitively.
• New labels are appended.
• Invalid entries are ignored safely.
• Catalog path is resolved from the first opened workspace folder.

Troubleshooting

If "installed but not working", check in order:

1. File mode is Markdown

• Bottom-right language mode in VS Code must show Markdown.

2. Cursor is inside supported fenced block body

• Must be inside ```mermaid, ```plantuml, or ```puml block content.
• On opening/closing fence lines, suggestions can be suppressed by design.

3. Settings are enabled

• Confirm the three settings above are true.

4. Trigger suggestions manually

• Use Ctrl+Space / Cmd+Space to verify provider response.

5. Reload extension host

• Run Developer: Reload Window after install/update.

6. Custom catalog issues (if enabled)

• Ensure JSON is valid and path exists at xmarkdown.customCatalogPath.
• If catalog was just edited, save and retry (catalog cache refreshes quickly).

Development

Install dependencies:

npm install

Build:

npm run build

Run tests:

npm run test

Run extension-host smoke tests:

npm run test:extension-host

CI

GitHub Actions workflow runs on push and pull request to main:

• Build
• Unit and integration tests
• VS Code extension-host smoke tests

Notes

• Completions are scoped to Mermaid/PlantUML fenced block content — no false positives in prose.
• Remote library update mechanisms are not included.