# Document Format

Folios uses Markdown files with optional YAML metadata. This page explains what's required, what's optional, and how metadata flows into tool responses.

## Minimum Requirements

To work with Folios, a document needs only two things:

1. **Filename**: Must follow the pattern `{id}_v{version}.md`
2. **H1 Title**: The first `#` heading becomes the document title

That's it. The simplest valid document:

```markdown
# My Document

Content here.
```

!!! tip "Metadata is optional"
    The YAML metadata block is entirely optional. If you don't include it, `author` and `date` will show as "NA" in responses because the tools always include these fields.

    You can add any fields you want to the metadata. See "Adding Custom Fields" below.

## File Naming

Files must follow the pattern `{id}_v{version}.md`:

```
documents/
├── 100001_v1.md    # Document 100001, version 1
├── 100001_v2.md    # Document 100001, version 2
└── 100002_v1.md    # Document 100002, version 1
```

- **ID**: Any positive integer (e.g., 100001, 999999)
- **Version**: Sequential integers starting at 1

## Metadata in Tool Responses

When you call `get_document_metadata` or `browse_catalog`, Folios returns structured metadata. Some fields are always present:

| Field | Source | Default |
|-------|--------|---------|
| `id` | Filename | — |
| `version` | Filename | — |
| `title` | First H1 heading | — |
| `author` | YAML metadata | "NA" |
| `date` | YAML metadata | "NA" |
| `chapters` | H2 headings | [] |

If `author` or `date` are missing from the metadata, they show as "NA" in responses.

## Adding Custom Fields

Any field you add to the YAML metadata is included in responses:

```markdown
---
author: "J. Smith"
date: "2025-01-15"
status: "Approved"
department: "Engineering"
priority: "High"
---

# Document Title

Content...
```

See [Configuration](configuration.md) to learn how Folios automatically discovers field values for filtering.

All these fields (`author`, `date`, `status`, `department`, `priority`) appear in the metadata response.

## Chapters

H2 headings (`##`) are automatically extracted as chapters:

```markdown
# Document Title

Introduction...

## Background

Content...

## Methodology

Content...
```

This produces `chapters: [{"title": "Background"}, {"title": "Methodology"}]`.

## Versioning

- Create new versions by incrementing the version number in the filename
- Keep previous versions for history (don't delete them)

!!! note "Superseded documents"
    Consider updating `status` to "Withdrawn" when a document is superseded by a newer version.

## Complete Example

A fully-featured document:

```markdown
---
author: "J. Smith"
date: "2025-01-15"
document_type: "Design Practice"
status: "Approved"
reviewer: "A. Johnson"
approver: "M. Williams"
---

# Stress Analysis Design Practice

This document defines the standard approach for stress analysis.

## Scope

Applies to all structural components.

## Methodology

Step-by-step process...

## References

Related documents...
```

## Next Steps

- See [Configuration](configuration.md) to learn how schema discovery works
- See [API Reference](api-reference.md) for complete tool documentation
