Documentation Deployment

The Retype source files live in docs/, while Retype generates the publishable static website into .retype/.

GitHub Pages setting

With the current project configuration, setting GitHub Pages to Deploy from a branch -> /docs folder is not correct. The /docs folder contains the Retype Markdown source, not the generated website. GitHub Pages would expose the source files rather than the finished Retype navigation and pages.

Use one of these approaches instead:

Recommended: GitHub Actions

This repository includes .github/workflows/retype-pages.yml. Configure GitHub Pages to use GitHub Actions, then the workflow will build the site and deploy the .retype/ directory automatically whenever changes are pushed to main. It can also be started manually from the Actions tab with Run workflow.

The workflow:

1. Checks out the repository.
2. Installs Node.js and the Retype CLI.
3. Runs retype build.
4. Uploads .retype/ as the Pages artifact.
5. Deploys that artifact to the github-pages environment.

In the repository settings, open Settings -> Pages and set Source to GitHub Actions. Do not select Deploy from a branch with the /docs folder for this layout.

From a local checkout, the equivalent build is:

retype build

The generated site is written to .retype/. The configured site URL is:

https://finickyspider.github.io/lsw-directory-walker

Release history and package versions are maintained separately on the GitHub Releases page and PyPI.

Manual deployment

If you do not use Actions, run retype build, then publish the contents of .retype/ through a hosting service or copy those generated files into the branch/folder configured for GitHub Pages. Do not replace the Markdown source in docs/ with generated files unless you intentionally change the Retype input/output layout.

Local preview

Preview the documentation with:

retype start

Build the static site with:

retype build

Retype should report the generated output directory as .retype/ and include all documentation pages and image assets.

Workflow permissions

The workflow requests contents: read, pages: write, and id-token: write, which are the permissions required by the official GitHub Pages artifact and deployment actions. The repository does not need a personal access token or deployment secret for this setup.