Dossiers
Dashboard Sign in Sign up

Installation

Get Dossiers up and running on your machine

Prerequisites

Dossiers is a command-line tool written in Rust. You can install it using either Cargo (the Rust package manager) or npm.

Install via Cargo (Recommended)

If you have Rust installed, you can install Dossiers directly from crates.io: 

cargo install dossiers

Don't have Rust? Install it from rustup.rs.

Install via npm

You can also install Dossiers using npm: 

npm install -g dossiers

Or use it directly with npx without installation: 

npx dossiers serve ./specs

Verify Installation

After installation, verify that Dossiers is available: 

dossiers --version

You should see the version number printed to the console.

Basic Usage

The most common command is serve, which starts a local development server: 

dossiers serve ./path/to/specs

This will:

  • Scan the specified directory for Markdown and AsciiDoc files
  • Generate a website with an index and individual pages for each spec
  • Start a local web server at http://localhost:8080
  • Watch for changes and automatically reload

Generating Static Sites

To generate a static site that you can deploy to any hosting service: 

dossiers build ./path/to/specs -o ./output

This creates a static HTML site in the ./output directory that you can upload to GitHub Pages, Netlify, Vercel, or any other static hosting service.

Command-Line Options

View all available options: 

dossiers --help

Common options include:

  • --port - Specify a different port for the development server
  • --config - Path to a configuration file (optional)
  • --title - Set a custom site title

Next Steps

Now that you have Dossiers installed, learn how to structure your specification repository:

Repository Structure → Metadata Guide →

Troubleshooting

Cargo installation fails

If you encounter errors during cargo install, make sure you have:

  • An up-to-date Rust toolchain (rustup update)
  • A C compiler installed (required for some dependencies)

Port already in use

If port 8080 is already in use, specify a different port: 

dossiers serve ./specs --port 3000

Git timestamps not working

Dossiers uses Git to determine file creation and modification dates. If your directory is not a Git repository, timestamps will fall back to file system metadata.