Source for the Poweradmin documentation published at docs.poweradmin.org.
Poweradmin itself lives in the main repository.
pip install -r requirements.txt # pinned toolchain, same versions CI uses
./build.sh # build with --strict, exactly as CI does
./build.sh serve # build, then serve on http://127.0.0.1:8000Edit the Markdown under docs/ and open a pull request. Every page has an edit link in the top
right on the site, which takes you straight to the right file.
A change has to pass five checks, all of which run on pull requests and again before anything deploys:
mkdocs build --strict- broken links, dead anchors, and pages missing from the navigationscripts/check_nav.py- every page underdocs/is in themkdocs.ymlnav, and every nav entry exists; the same rule as the build's, kept separate so it survives a change of build enginescripts/check_site_paths.py- every localsrcandhrefin the built site resolves, including paths written in raw HTML, which the strict build does not checkmarkdownlint-cli2- the house style: dash bullets, four-space nested indentation, blank lines around lists and code fences- a check that no code fence sits unindented after a numbered list item, which would detach it from the step it belongs to
Run them locally with ./build.sh (the nav check, the strict build and the path check) and npx markdownlint-cli2.
Two pages are generated from the Poweradmin source and must not be edited by hand:
| Page | Generated from |
|---|---|
docs/configuration/settings-reference.md |
config/settings.defaults.php via scripts/gen_settings_reference.py |
docs/api/openapi.json (rendered by docs/api/reference.md) |
the API controller annotations, via composer docs:api:json |
A weekly workflow re-derives both from the Poweradmin repository and fails if they have drifted. It
also checks that every PA_* variable the Docker entrypoint reads is documented in DOCKER.md.
Two front-end libraries are committed under docs/assets/vendor/ instead of coming from MkDocs
plugins, so the site does not depend on a plugin for either and loads nothing from a third-party
host:
| Library | Version | Used by |
|---|---|---|
| swagger-ui-dist | 5.33.3 | docs/api/swagger.html, embedded by docs/api/reference.md |
| glightbox | 3.3.1 | docs/js/lightbox.js, which wraps content images |
Dependabot does not track them. To update one, copy the same files from the new npm tarball and
change the version here. swagger-ui-dark.css is not part of swagger-ui-dist; keep it.
Pushing to main builds the site and publishes it to
poweradmin.github.io. There is no manual
deploy step - use the "Run workflow" button on the Deploy Documentation workflow if you need to
republish without a commit.
See LICENSE.