Repository Structure

Basic Structure

A Dossiers repository is simply a directory containing Markdown or AsciiDoc files. The simplest structure looks like this:

specs/
├── 0001-user-authentication.md
├── 0002-payment-processing.md
├── 0003-database-schema.md
└── 0004-api-design.md

Each file becomes a specification in your generated site.

File Naming

Dossiers automatically extracts a specification ID from the filename. The recommended pattern is to use a zero-padded numeric prefix:

• 0001-feature-name.md
• 0042-another-spec.md
• 0100-important-change.md

The numeric prefix helps maintain order and makes it easy to reference specs. The rest of the filename should be a descriptive slug using lowercase letters and hyphens.

Directory Structure

You can organize specifications in subdirectories. Each spec can have its own folder containing the document and related assets:

specs/
├── 0001-user-authentication/
│   ├── user-authentication.md
│   └── diagrams/
│       └── auth-flow.png
├── 0002-payment-processing/
│   ├── payment-processing.md
│   └── architecture.svg
└── 0003-database-schema/
    └── database-schema.md

This structure makes it easier to keep related assets together with each specification.

Assets and Images

Store images, diagrams, and other assets alongside your specifications. Reference them using relative paths:

![Authentication Flow](./diagrams/auth-flow.png)

Or you can use a shared assets directory:

specs/
├── 0001-feature.md
├── 0002-another.md
└── assets/
    ├── diagrams/
    │   ├── auth-flow.png
    │   └── api-endpoints.svg
    └── screenshots/
        └── ui-mockup.png

File Formats

Dossiers supports two document formats:

Markdown (.md)

The recommended format. Supports GitHub-flavored Markdown with:

• Tables
• Fenced code blocks with syntax highlighting
• Task lists
• Strikethrough
• Automatic linking

AsciiDoc (.adoc)

Basic AsciiDoc support is available. Most common AsciiDoc features work, including headings, lists, tables, and code blocks. Some advanced features may not be supported.

Recommended Practices

Use Sequential IDs

Start with 0001 and increment for each new spec. This makes it easy to reference specifications and see the chronological order of proposals.

Keep Assets Close

Store images and diagrams in the same directory as the spec that uses them, or in a clearly named subdirectory. This makes it easier to move or archive specs.

One Spec Per File

Each specification should be a separate file. Don't combine multiple specs into a single document—this makes it harder to review and track changes.

Use Git

Store your specs in a Git repository. Dossiers will automatically use Git history to determine creation and modification dates, and can detect pull requests.

Example Repositories

See how other projects structure their specification repositories:

• Rust RFCs - Large collection with one file per RFC
• React RFCs - Each RFC in its own directory with assets
• Joyent RFDs - Mixed structure with AsciiDoc and Markdown

Next Steps

Learn about the metadata you can add to your specifications: