Documentation

Legend allows you to attach markdown documentation files directly to entities. This keeps documentation close to the entities it describes, making it easy to find, search, and maintain. Instead of scattering runbooks, architecture notes, and guides across wikis and shared drives, you can store them alongside the services, projects, and resources they document.

What Is Entity Documentation?

Entity documentation consists of markdown files stored alongside an entity’s YAML definition. Each documentation file has:

A title (displayed as a tab in the UI)
Markdown content (supporting full markdown syntax)
A file path (stored in the entity’s directory)

Documentation is searchable, meaning the content is indexed and appears in search results. When you search for a term, Legend searches both entity metadata (names, descriptions, tags) and documentation content.

Creating Documentation

You can create documentation in two ways:

During entity creation: When creating an entity using the wizard, Step 3 (Documentation) allows you to add documentation files. Click “Add Documentation” to create a new file, enter a title, and write the markdown content.

After entity creation: To add documentation to an existing entity:

Open the entity detail drawer
Click the Docs tab
Click the Add Documentation button
Enter a title for the documentation file
Write the markdown content
Click Save

You can add multiple documentation files to a single entity. Each file appears as a separate tab in the Docs section.

Editing Documentation

The DocManager provides a tabbed interface for managing documentation files:

Viewing documentation:

Click the Docs tab in the entity detail drawer
Click a documentation tab to view that file
The markdown content is rendered with proper formatting

Editing documentation:

Click the Edit button in the documentation viewer
The markdown editor opens with the current content
Make your changes in the editor
Click Save to apply changes
Click Cancel to discard changes

Adding new documentation:

Click the Add Documentation button in the DocManager
Enter a title and content
Click Save to create the file

Deleting documentation:

Click the Delete button next to a documentation tab
Confirm the deletion
The file is removed from the entity

The Markdown Editor

Legend provides a built-in markdown editor with the following features:

Syntax support:

Full markdown syntax (headings, lists, links, images, code blocks)
Code blocks with syntax highlighting for multiple languages
Tables, blockquotes, and horizontal rules
Inline code and code blocks

Editor features:

Live preview (toggle between edit and preview modes)
Syntax highlighting in the editor
Auto-save (changes are saved when you click Save)
Full-screen editing mode for large documents

Best practices for documentation:

Use clear, descriptive titles for documentation files
Structure content with headings (H2, H3, H4)
Include code examples where appropriate
Link to related entities using relative paths
Keep documentation focused and concise

Documentation Search

Documentation content is fully searchable:

Search behavior:

When you search for a term, Legend searches both entity metadata and documentation content
Search results show which documentation file matched and display a snippet of the matching content
You can filter search results to show only documentation matches

Search tips:

Use specific terms to find relevant documentation
Search for service names, error messages, or procedure steps
Use filters to narrow results to specific entity types or categories

File Storage Location

Documentation files are stored in the Legend data directory alongside entity YAML files:

data/
└── catalog/
    └── landmark/
        └── billing-api/
            ├── billing-api.yaml          # Entity definition
            └── docs/                      # Documentation directory
                ├── runbook.md            # Documentation file
                ├── architecture.md       # Another documentation file
                └── deployment.md         # Yet another documentation file

Each entity has its own directory, and documentation files are stored in a docs/ subdirectory. The file names are derived from the documentation titles (converted to kebab-case).

Direct file editing: You can edit documentation files directly using a text editor or through version control. Changes to files in the data directory are reflected in Legend after a container restart or data reload.

Documentation vs Entity Description

Legend provides two places for text content:

Entity description:

A brief summary (one or two sentences)
Displayed on the entity card
Used for quick identification
Limited in length

Documentation files:

Detailed content (unlimited length)
Displayed in the Docs tab
Used for runbooks, guides, architecture notes, etc.
Full markdown support
Multiple files per entity

Use the entity description for a concise summary that helps people identify the entity at a glance. Use documentation files for detailed information that people need to reference.

Best Practices for Entity Documentation

Create documentation for important entities:

Services with complex operations or dependencies
Projects with detailed plans or timelines
Resources with configuration or maintenance procedures
Any entity where people frequently ask “how do I…” or “where is the documentation for…”

Keep documentation current:

Update documentation when processes change
Remove outdated information
Add new documentation as the entity evolves
Review documentation periodically to ensure accuracy

Structure documentation clearly:

Use headings to organize content
Include a table of contents for long documents
Use code blocks for commands and configuration
Add links to related entities or external resources

Make documentation discoverable:

Use clear, descriptive titles
Include keywords that people might search for
Reference the documentation in the entity description if relevant
Link to documentation from runbooks or other external resources

Creating Entities

Editing Entities

Search and Discovery