Expert guidance for creating, structuring, and maintaining technical documentation in Meldoc.

Meldoc File Format Requirements

File Extension

•Files must have extension: *.meldoc.md (configurable in meldoc.config.yml)

YAML Frontmatter (MANDATORY)

Every Meldoc document MUST start with YAML frontmatter between --- delimiters:

Required fields:

•title: Document display title (string)
•alias: Unique document identifier (string, kebab-case, stable) - required for publishing

Optional fields:

•parentAlias (or parent_alias): Parent document alias for hierarchy
•workflow: draft | published (default: published) - only add if draft
•visibility: visible | hidden (default: visible) - only add if hidden
•exposure: inherit | private | unlisted | public (default: inherit) - keep default unless explicitly requested

Example frontmatter:

yaml

---
alias: getting-started-guide
title: Getting Started Guide
parentAlias: documentation
workflow: published
visibility: visible
---

Best Practices

Document Structure

Good documentation has:

•Clear, descriptive titles in frontmatter
•Logical hierarchy (H2 → H3 → H4) - NO H1 in content (title comes from frontmatter)
•Introduction explaining the purpose
•Step-by-step instructions with examples
•Links to related documents using magic links
•Code examples with syntax highlighting

Example structure:

markdown

---
alias: feature-name
title: Feature Name
parentAlias: features
---

Brief description of what this feature does.

## Overview

High-level explanation...

## Prerequisites

What users need before starting...

## Step-by-Step Guide

1. First step with details
2. Second step with code example
3. Third step with screenshot

## Troubleshooting

Common issues and solutions...

## Related Documentation

- [[api-reference]]
- [[getting-started]]

Creating Documents

When creating new documents, Claude should:

•
Ask clarifying questions:
- •What is the target audience? (developers, end-users, admins)
- •What level of detail is needed?
- •Are there existing related documents?
•
Use docs_tree first to understand the structure

•

Create with proper frontmatter and metadata:

javascript

// Example using docs_create
{
  title: "Clear, Descriptive Title",
  alias: "clear-descriptive-title", // kebab-case, stable identifier
  contentMd: `---

alias: clear-descriptive-title title: Clear, Descriptive Title parentAlias: parent-doc-alias

Overview

Content starts here with H2, not H1... `, projectId: "project-uuid", parentAlias: "parent-doc-alias" // Optional }

code


4. **Link to related documents** using magic links: `[[doc-alias]]` or cross-project: `[[project-alias::doc-alias]]`

### Updating Documents

Before updating:

1. Use `docs_get` to read current content
2. Preserve existing frontmatter and structure unless requested otherwise
3. Use `expectedUpdatedAt` for optimistic locking
4. Explain what changed in the conversation

### Documentation Templates

**API Endpoint Documentation:**

```markdown
---
alias: api-endpoint-resource
title: GET /api/v1/resource
parentAlias: api-reference
---

Brief description of what this endpoint does.

## Request

**Method:** GET
**URL:** `/api/v1/resource`
**Authentication:** Required

### Parameters

| Name | Type | Required | Description |
|:-----|:-----|:----------|:------------|
| id   | string | Yes | Resource identifier |

### Example Request

\`\`\`bash
curl -X GET https://api.example.com/v1/resource/123 \
-H "Authorization: Bearer TOKEN"
\`\`\`

## Response

### Success (200 OK)

\`\`\`json
{
"id": "123",
"data": "..."
}
\`\`\`

### Errors

- `400` - Bad Request
- `404` - Not Found
- `500` - Server Error

## Related Endpoints

- [[api-list-resources]]
- [[api-create-resource]]

Feature Documentation:

markdown

---
alias: feature-name
title: Feature Name
parentAlias: features
---

One-line description of what this feature enables.

## What is [Feature]?

Explain the feature in simple terms...

## Why Use [Feature]?

Key benefits:
- Benefit 1
- Benefit 2
- Benefit 3

## How It Works

High-level overview of the mechanism...

## Quick Start

1. Step 1
2. Step 2
3. Step 3

## Examples

### Example 1: Common Use Case

Description and code...

\`\`\`javascript
// Example code
\`\`\`

### Example 2: Advanced Use Case

Description and code...

## Configuration

Available options...

## Troubleshooting

Common issues...

## FAQ

Frequently asked questions...

Tutorial Documentation:

markdown

---
alias: how-to-accomplish-task
title: How to [Accomplish Task]
parentAlias: tutorials
---

Learn how to [accomplish task] in [estimated time].

## What You'll Build

Brief description and maybe a screenshot...

## Prerequisites

- Prerequisite 1
- Prerequisite 2

## Step 1: [First Step]

Detailed instructions...

\`\`\`javascript
// Example code
\`\`\`

## Step 2: [Second Step]

More instructions...

## Step 3: [Final Step]

Wrap up...

## Next Steps

- Try [[related-tutorial]]
- Learn about [[advanced-topic]]
- Explore [[related-feature]]

Meldoc-Specific Features

Internal Links (Magic Links)

Preferred method - Link to other documents using aliases:

markdown

See the [[api-reference]] for details.

For cross-project links:
See [[other-project::setup-guide]] for details.

Alternative methods:

•Standard markdown: [Link Text](./path/to/doc.meldoc.md)
•External: [Link Text](https://example.com)
•Reference links: [Link text][ref] with [ref]: https://example.com

Mermaid Diagrams

Meldoc supports Mermaid diagrams:

markdown

\`\`\`mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Alternative]
\`\`\`

Supported types:
- graph, flowchart
- sequenceDiagram
- classDiagram
- stateDiagram
- erDiagram
- gantt
- pie
- mindmap

Task Lists

Use task lists for checklists:

markdown

- [ ] Unchecked task
- [x] Completed task
- [ ] Another task

Backlinks

Check who references your document:

javascript

// Use docs_backlinks to find
docs_backlinks({ docId: "your-doc-id" })

Document Trees

Organize hierarchically:

javascript

docs_create({
  title: "Child Document",
  alias: "child-document",
  contentMd: `---
alias: child-document
title: Child Document
parentAlias: parent-doc
---

## Content...
`,
  parentAlias: "parent-doc"
})

Tips for AI-Assisted Writing

•Start with outline - Use docs_create with basic structure first
•Iterate sections - Update one section at a time
•Check existing docs - Use docs_search to avoid duplication
•Link liberally - Use docs_links to see connection opportunities
•Review tree - Use docs_tree to ensure logical hierarchy
•Always include frontmatter - Never create documents without YAML frontmatter
•Use magic links - Prefer [[alias]] over relative paths when possible

Common Patterns

Creating Documentation Series

javascript

// 1. Create parent document (overview)
docs_create({
  title: "User Authentication Guide",
  alias: "user-authentication-guide",
  contentMd: `---
alias: user-authentication-guide
title: User Authentication Guide
---

## Overview

Authentication overview...
`
})

// 2. Create child documents
docs_create({
  title: "OAuth Setup",
  alias: "oauth-setup",
  contentMd: `---
alias: oauth-setup
title: OAuth Setup
parentAlias: user-authentication-guide
---

## OAuth Setup

Detailed steps...
`,
  parentAlias: "user-authentication-guide"
})

docs_create({
  title: "Session Management",
  alias: "session-management",
  contentMd: `---
alias: session-management
title: Session Management
parentAlias: user-authentication-guide
---

## Sessions

How sessions work...
`,
  parentAlias: "user-authentication-guide"
})

Refactoring Documentation

javascript

// 1. Search for related content
docs_search({ query: "authentication" })

// 2. Review each document
docs_get({ docId: "..." })

// 3. Consolidate or split as needed
docs_update({ docId: "...", contentMd: "..." })

// 4. Update links using docs_links

Migration from Other Platforms

When migrating content:

•Add frontmatter - Every document needs YAML frontmatter
•Convert H1 to title - Move H1 content to frontmatter title field
•Update headings - Start content with H2, not H1
•Convert links - Update to magic links [[alias]] format
•Add aliases - Generate stable kebab-case aliases
•Create hierarchy - Set up parent-child relationships
•Preserve structure - Keep original organization initially

Markdown Syntax Reference

Headings

•Use H2 (##) as the first heading in content
•H1 is provided by frontmatter title field
•Hierarchy: H2 → H3 → H4 → H5 → H6

Text Formatting

•Bold: **text** or __text__
•Italic: *text* or _text_
•~~Strikethrough~~: ~~text~~
•Combined: ***bold italic***, **bold and _italic_**

Code

•Inline: `code`
•Blocks: ```language with syntax highlighting
•Supported languages: javascript, typescript, python, html, css, json, bash, etc.

Lists

•Bullet: -, *, or +
•Numbered: 1. 2. 3.
•Nested: indent with 2 spaces
•Task lists: - [ ] unchecked, - [x] checked

Tables

markdown

| Header 1 | Header 2 |
|:---------|:---------:|
| Left     | Center   |
| Aligned  | Aligned  |

Alignment:

•:--- - left
•:---: - center
•---: - right

Other Elements

•Blockquotes: > quoted text
•Horizontal rules: --- or *** or ___
•Escape special chars: \* \# \[ \]

Quality Checklist

Before finalizing documentation:

Common Mistakes to Avoid

•Missing frontmatter - Every document MUST have YAML frontmatter
•Using H1 in content - Title comes from frontmatter, start with H2
•Missing alias - Required for publishing, must be kebab-case
•Wrong link format - Use [[alias]] for internal links, not [text](doc-alias)
•Inconsistent aliases - Aliases should be stable, don't change them
•No parent hierarchy - Use parentAlias to organize documents
•Forgetting workflow - Set workflow: draft for work-in-progress docs