Dossiers
Dashboard Sign in Sign up

Configuration

Customize your Dossiers project

Configuration File

Dossiers projects can be customized using a dossiers.toml configuration file in your repository root. This file uses the TOML format and supports various options for metadata, statuses, and project settings. 

# dossiers.toml
title = "My Specifications"
description = "Product and technical specifications"

statuses = ["Draft", "Review", "Published", "Abandoned"]
default_status = "Published"

Basic Settings

title

The name of your project, displayed in the site header. 

title = "ACME Product Specifications"

description

A brief description of your project (used by deployment infrastructure). 

description = "Technical specifications for ACME products"

Title Strategy

Controls how each specification's display title is chosen. By default Dossiers tries the document's metadata title, then its first heading, then the filename — but you can pin a single source when a repo's convention makes the default pick the wrong thing (for example, when every document's first heading is a generic # Summary).

title_strategy

One of the following values (defaults to auto):

  • auto - Metadata title, then the first heading, then the filename. A leading metadata bullet list suppresses the heading, so a generic # Summary after it never wins.
  • metadata - The title declared in the document's frontmatter or a leading - title: bullet (respecting field_aliases), falling back to the filename.
  • heading - The document's first heading, falling back to the filename.
  • filename - Always the filename (with any id prefix and extension stripped), ignoring metadata and headings.

Whatever the strategy, the filename is always the ultimate fallback, so every specification keeps a title. 

# Ignore headings and derive the title from the filename
title_strategy = "filename"

Status Configuration

Define the valid status values for your specifications.

statuses

An array of valid status values. Documents can only have one of these statuses. 

statuses = ["Draft", "Discussion", "Published", "Completed", "Abandoned"]

default_status

The status assigned to documents when merged to the main branch. 

default_status = "Published"

new_status

The status assigned to newly created documents. 

new_status = "Draft"

Field Aliases

Map custom field names in your documents to standard fields. This is useful if you're migrating from another system or prefer different terminology. 

[field_aliases]
title = "Feature Name"
created = "Start Date"
status = "State"
updated = "Last Modified"

With this configuration, you can use Feature Name instead of title in your frontmatter, and Dossiers will map it correctly.

Custom Metadata Fields

Add custom fields beyond the standard ones (title, status, created, updated, authors, links). Each custom field is defined in an [[extra_metadata_fields]] section.

Field Properties

  • name - The field name in your document frontmatter
  • type - Data type: string, date, boolean, number, or markdown
  • required - Whether the field must be present (default: false)
  • display_name - User-friendly name shown in the UI
  • link_format - URL template for linking field values
  • aliases - Alternative field names

Example: Release Version

[[extra_metadata_fields]]
name = "initialRelease"
type = "string"
display_name = "Initial Release"
link_format = "https://github.com/org/repo/releases/tag/{value}"

Example: Target Milestone

[[extra_metadata_fields]]
name = "milestone"
type = "string"
display_name = "Target Milestone"
aliases = ["targetMilestone", "target_milestone"]

Example: Priority

[[extra_metadata_fields]]
name = "priority"
type = "number"
display_name = "Priority"
required = true

Example: Deprecated Flag

[[extra_metadata_fields]]
name = "deprecated"
type = "boolean"
display_name = "Deprecated"

Example: Summary

[[extra_metadata_fields]]
name = "summary"
type = "markdown"
display_name = "Summary"

The markdown type renders the field value as HTML, allowing you to use formatting, links, and other Markdown features.

Empty Values

Define which values should be treated as "not provided" in metadata: 

empty_values = ["n/a", "tbd", "none", "unknown"]

These values are normalized (trimmed, lowercased, parentheses removed) before comparison.

Complete Example

Here's a full configuration file showing all available options: 

# Project metadata
title = "ACME Product Specifications"
description = "Technical and product specifications"

# How each spec's title is chosen: auto | metadata | heading | filename
title_strategy = "auto"

# Status configuration
statuses = ["Draft", "Review", "Published", "Completed", "Abandoned"]
default_status = "Published"
new_status = "Draft"

# Empty value handling
empty_values = ["n/a", "tbd", "none"]

# Map custom field names to standard fields
[field_aliases]
title = "Feature Name"
created = "Start Date"
status = "State"

# Custom metadata fields
[[extra_metadata_fields]]
name = "initialRelease"
type = "string"
display_name = "Initial Release"
link_format = "https://github.com/org/repo/releases/tag/{value}"

[[extra_metadata_fields]]
name = "milestone"
type = "string"
display_name = "Target Milestone"
aliases = ["targetMilestone"]

[[extra_metadata_fields]]
name = "priority"
type = "number"
display_name = "Priority"

[[extra_metadata_fields]]
name = "deprecated"
type = "boolean"
display_name = "Deprecated"

[[extra_metadata_fields]]
name = "summary"
type = "markdown"
display_name = "Summary"

Using Configuration

Place dossiers.toml in your repository root, and Dossiers will automatically detect and use it. You can also specify a custom configuration file: 

dossiers serve ./specs --config ./custom-config.toml

Next Steps

Now that you know how to configure your project, start building your specification site:

Installation → Metadata Guide →