How-to guides

Check formatting in CI

Make a CI build fail when an AsciiDoc file in the repository is not formatted.

Check with GitHub Actions

Add a workflow file, such as .github/workflows/adocfmt.yml:
```
name: adocfmt

on:
  pull_request:
  push:
    branches: [main]

jobs:
  adocfmt:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: ypfaff/adocfmt@v0
```
The action runs adocfmt --check .. The job fails when a file is not formatted, when a document is refused, or when adocfmt reports another error. To check other paths, set the args input; see Inputs.
Choose the ref in uses:, which also picks the adocfmt version:
- ypfaff/adocfmt@v0 follows every new 0.x.y release.
- ypfaff/adocfmt@v0.1.0 stays on release 0.1.0.
Leave the version input unset. Versioning explains why. To keep the ref up to date, let a dependency update tool such as Dependabot or Renovate update it.
Tip
For supply chain security, GitHub recommends pinning an action to a full commit SHA, because a tag can be moved: uses: ypfaff/adocfmt@<sha> # v0.1.0. See Using third-party actions.

Check in another CI system

Install adocfmt on the build machine, as described in Install adocfmt.
Add a build step that runs adocfmt with --check on the repository:
```
adocfmt --check .
```
adocfmt prints the name of each file that is not formatted and exits with a code other than 0. The build fails on that code. For what each exit code means, see Exit codes.

Fix a failed check

Run adocfmt --write . locally and commit the result. If adocfmt refuses a document, see Refusal findings.

View the source on GitHub