Site Documentation

This site is an mdBook built from the docs/ directory and published at cowboy.rs.

Layout

docs/
  book.toml      # mdBook configuration
  src/           # Markdown sources (SUMMARY.md is the table of contents)
  theme/         # custom theme assets (cowboy-hat)
  book/          # build output — git-ignored, regenerated by mdbook

docs/book/ is generated and excluded from version control. Edit files in docs/src/ and add new pages to docs/src/SUMMARY.md.

book.toml

Key settings (docs/book.toml):

src = "src", build output build-dir = "book"
default-theme = "navy", preferred-dark-theme = "navy"
site-url = "https://cowboy.rs/", cname = "cowboy.rs"
git-repository-url = "https://github.com/dmadisetti/cowboy" and an edit-url-template pointing at docs/src/{path}
search and section folding enabled
a custom “cowboy-hat” mark styled via additional-css (theme/css/cowboy-hat-fixed.css)

Building

# Nix (preferred — pins mdbook)
nix build .#docs        # output in ./result, the rendered book

# Or directly with mdbook
cd docs
mdbook build            # writes docs/book/
mdbook serve            # live-reload preview on http://localhost:3000

The flake’s docs package runs mdbook build and installs the book/ output.

Adding a page

Create the Markdown file under docs/src/ in the appropriate section.
Add an entry to docs/src/SUMMARY.md (pages not listed there are orphans and will not appear in the navigation).
Run mdbook build (or mdbook serve) and check the page renders.

Verifying rendering with the browser

Because the harness can drive a browser (see Browser Automation), an agent can serve the built book and confirm pages render before publishing:

mdbook serve          # or serve docs/book/ with any static server
cowboy-browser navigate http://localhost:3000
cowboy-browser screenshot ./home.png

This is optional — mdbook build succeeding plus correct SUMMARY.md entries and resolving internal links is the baseline check.