Prerequisites

• .NET 9.0 SDK
• Node.js 22.13.1 (LTS)
  • Aspire 9.4.1

    dotnet workload install aspire
    

Validate the fully assembled documentation

dotnet run --project aspire

Will spin up all our services and clone and build all the documentation sets.

dotnet run --project aspire -- --assume-cloned --skip-private-repositories

--assume-cloned will assume a documentation set set is already cloned if available locally.

--skip-private-repositories will skip cloning private repositories. It will also inject our `docs-builder docs into the navigation. This allows us to validate new features' effect on the assembly process.

Our Integration Tests use this exact command to validate the assembler builds.

Continuously build all assets during development.

./build.sh watch

This will monitor code, cshtml template files & static files and reload the application if any changes.

Web assets are reloaded through parcel watch and don't require a recompilation.

Markdown files are refreshed automatically through livereload

Code or layout changes will relaunch the server automatically

CLI reference maintenance

When you add or change CLI options in src/tooling/docs-builder/Commands/, regenerate the checked-in schema so CI and the published CLI reference stay in sync:

dotnet run --project src/tooling/docs-builder -- __schema > docs/cli-schema.json

Commit the updated docs/cli-schema.json with your code changes. CI compares the schema (ignoring the version field) and fails if it has drifted.

The schema drives auto-generated parameter tables and usage synopses on CLI reference pages. For behavior, workflows, and examples that the schema cannot express, also update supplemental files under docs/cli/ (see Writing supplemental content).

Working on non-trivial changes

Before starting implementation on anything non-trivial — a new directive, a CLI command, a change that touches more than one project — write a short plan first: a few paragraphs (in the PR description, a linked issue, or handed to an agent as a prompt) stating what's changing and an explicit definition of done. This isn't bureaucracy for its own sake: it's what lets a change be scoped to a single sitting/session instead of sprawling as the "actual" requirements get discovered mid-implementation. Trivial fixes (typos, one-line bug fixes, dependency bumps) don't need this.

Release Process

This section outlines the process for releasing a new version of this project.

Versioning

This project uses Semantic Versioning and its version is automatically determined by release-drafter based on the labels of the pull requests merged into the main branch.

See the release-drafter configuration for more details.

Git Hooks with Husky.Net

This repository uses Husky.Net to automatically format and validate code before commits and pushes.

What Gets Checked

Pre-commit hooks (run on staged files):

• prettier - Formats TypeScript, JavaScript, CSS, and JSON files in src/Elastic.Documentation.Site/
• typescript-check - Type checks TypeScript files with tsc --noEmit (only if TS files are staged)
• eslint - Lints and fixes JavaScript/TypeScript files

Pre-push hooks (run on files being pushed):

• dotnet-lint - Lints C# and F# files using ./build.sh lint (runs dotnet format --verify-no-changes)

Installation

Husky.Net is included as a dotnet tool. After cloning the repository, restore the tools:

dotnet tool restore

Then install the git hooks:

dotnet husky install

That's it! The hooks will now run automatically on every commit and push.

Usage

Once installed, hooks run automatically when you commit or push:

git add .
git commit -m "your message"  # Pre-commit hooks run here
git push                       # Pre-push hooks run here

Note: If hooks modify files (prettier, eslint), the commit will fail so you can review the changes. Simply stage the changes and commit again:

git add -u
git commit -m "your message"

If the dotnet-lint hook fails during push, you need to fix the linting errors and commit the fixes before pushing again.

Manual Execution

You can test hooks without committing or pushing:

# Run all pre-commit tasks
dotnet husky run --group pre-commit

# Run all pre-push tasks
dotnet husky run --group pre-push

# Test individual tasks
dotnet husky run --name prettier
dotnet husky run --name typescript-check
dotnet husky run --name eslint
dotnet husky run --name dotnet-lint

Configuration

Hook configuration is defined in .husky/task-runner.json. See the Husky.Net documentation for more details.

Creating a New Release

To create a new release trigger the release workflow on the main branch.

Every time a pull request is merged into the main branch, release-drafter will create a draft release or update the existing draft release in the Releases page.

To create a new release you need to publish the existing draft release created by release-drafter.