Deploy cargo doc Output to GitHub Pages

cargo doc writes to target/doc with no top-level index, so publishing to Pages means adding an index.html that redirects to your crate.

Rust API docs are static HTML, so hosting them on GitHub Pages is straightforward, with one wrinkle: cargo doc does not create a root index page. You add a small redirect.

What it does

After cargo doc --no-deps, the browsable entry point is target/doc/<crate_name>/index.html, not target/doc/index.html. Publishing to Pages means uploading target/doc and injecting a root index.html that redirects to the crate, so the Pages URL lands somewhere useful.

Common usage

bash

RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
# add a root redirect to the crate index
echo '<meta http-equiv="refresh" content="0;url=my_crate/index.html">' \
  > target/doc/index.html

GitHub Actions

.github/workflows/docs.yml

permissions:
  contents: read
  pages: write
  id-token: write
steps:
  - uses: actions/upload-pages-artifact@v3
    with:
      path: target/doc
  - uses: actions/deploy-pages@v4

In CI

Grant pages: write and id-token: write for the artifact deploy flow. Underscores matter: a crate named my-crate becomes my_crate in the doc path, so the redirect target must use the underscore form. Cache target/ to avoid recompiling on every docs run.

Common errors in CI

A deployed site that 404s at the root means the index.html redirect is missing or points at the hyphenated crate name instead of the underscore form. Error: Failed to create deployment (status: 403) means pages: write/id-token: write permissions are absent. Get Pages site failed means Pages is not enabled for the repo.