Braised Docs

Contributing

This page documents conventions for contributors.

Development setup

git clone https://github.com/ravindk89/braised
cd braised
go build ./...
go vet ./...

Both commands should succeed with no output.

Code conventions

Error handling

Always wrap errors with context:

if err != nil {
    return fmt.Errorf("parsing nav %q: %w", path, err)
}

Never use _ to discard an error without a documented reason inline.

Build errors

Page-level errors go to the errs.Collector — they do not abort the build. Only errors that prevent the build from starting at all (missing config, unreadable docs directory) are returned as hard errors from build.Build().

Struct initialization

Always use named fields:

// correct
return &NavNode{
    Label:    label,
    Path:     valNode.Value,
    URL:      url,
}

// incorrect
return &NavNode{label, valNode.Value, url, nil, false}

Packages

Package names are singular and lowercase: config, nav, build — not configs, navigation, builder.

Add new packages only when a clear boundary exists. Prefer extending an existing package over creating a new one for small additions.

New libraries

Before adding a dependency, check whether stdlib or an existing dependency covers the need. Any new dependency should be noted in a PR description with a brief justification.

Testing

Tests follow a two-tier strategy:

Unit tests — table-driven, in _test.go files alongside the package under test. Use github.com/stretchr/testify/assert and require. Each test case in the table should cover one distinct behavior or edge case, named descriptively.

Integration tests — fixture directories under internal/testutil/fixtures/. Each fixture is a minimal site directory with source files and a want.yaml that declares expected outputs (page HTML snippets, error counts, warning messages). The test runner builds the fixture site and asserts every want entry.

When adding a new feature or fixing a bug, cover it at the appropriate tier:

  • Parser/renderer bugs: unit test in internal/block/ or internal/parser/
  • Multi-file or cross-page behavior: integration fixture
  • Pure logic (nav, config, chunker): unit test in the relevant package

Run tests with:

go test ./...

Dogfooding

This documentation site is built with braised build at the repository root. When making changes to the build pipeline, verify the docs still build:

go build -o braised . && ./braised build

A clean build of the docs is a basic smoke test for any change to the core pipeline.