Static documentation hosting

Docs want files, versioning, and boring deploys

Software documentation succeeds when URLs are stable, pages are searchable by the browser’s find, and a bad publish can be undone. Static site generators dominate this niche: MkDocs, Docusaurus, Eleventy doc templates, Hugo docs themes, VitePress. All of them can emit a directory StaticHost can serve.

StaticHost does not build docs for you. Run the generator in CI or locally, upload output, preview on HTTPS, certify custom domains after DNS verifies, roll back from history. nginx: try_files $uri $uri/ =404—fine for doc trees with real paths, hostile to SPA-only doc UIs that forget to export HTML.

MkDocs

pip install mkdocs mkdocs-material
mkdocs build
ls site
cd site && zip -r ../docs.zip .

mkdocs.yml keys:

site_name: My Project
site_url: https://docs.example.com/

Set site_url to the eventual HTTPS docs hostname. Deploy site/ contents (MkDocs’ default output).

Docusaurus

Docusaurus 2+ can build static files:

npm ci
npm run build
ls build
cd build && zip -r ../docusaurus.zip .

Config (docusaurus.config.js) — url and baseUrl:

const config = {
  url: 'https://docs.example.com',
  baseUrl: '/',
  // ...
}

baseUrl: '/project/' leftovers from GitHub Pages will break root hosting on StaticHost. Client-side routing exists in Docusaurus; exported pages should still produce real files for primary routes—verify hard refresh on a deep doc path after deploy. If something 404s, fix the export, do not invent nginx fallback.

VitePress / Eleventy / Hugo

VitePress: vitepress build → upload output dir; base must be '/' for root.
Eleventy: Eleventy guide.
Hugo: Hugo guide.

Multi-version docs

Common patterns: separate StaticHost sites per major version (docs-v1, docs-v2) on Scale/Business, or subpaths generated into one tree (/v1/, /v2/). Subpaths require generator base/baseUrl discipline. Site counts: Starter 1, Pro 3, Scale 10, Business 30 ($9/$30/$65/$130) with 2/10/30/100 GB. Pro adds staging—useful for “next” docs.

Search

Client-side search indexes shipped as JSON/JS work on static hosts. Algolia DocSearch-style integrations call external APIs. No server-side search daemon on StaticHost.

CI sketch

npm ci && npm run build
# or mkdocs build
# upload build/ or site/ via your preferred path to StaticHost

GitHub integration must see built files—git deploy. No remote npm on the host.

Review workflow

PR builds docs in CI.
Deploy artifact to staging site (Pro+).
QA HTTPS preview/staging hostname.
Promote to production site.
Roll back if a sidebar regression escapes.

Custom domain docs.example.com—custom domain guide. No email/cPanel/CDN product/forever-free (trial ~1 day). No WordPress docs plugins here.

A realistic week shipping static documentation hosting

Monday starts with a broken relative CSS path that only appears once the files leave a designer’s laptop. You flatten the zip so index.html sits at the archive root, redeploy to StaticHost, and HTTPS preview finally matches local intent. Plans: Starter $9 (1 site, 2 GB), Pro $30 (3 sites, 10 GB, staging), Scale $65 (10 sites, 30 GB), Business $130 (30 sites, 100 GB, teams).

Wednesday adds a custom domain. DNS is created exactly as the dashboard specifies; verification lags an hour; the certificate appears afterward. Someone asks whether email is included—you point them at a mail vendor and keep MX untouched. Deploy history supports rollback when a publish goes wrong.

Thursday an engineer enables history-mode routing for a “cleaner URL.” Refresh on a nested path 404s. You revert to hash routing for the week’s deadline and schedule prerender work properly instead of inventing an nginx rewrite StaticHost will not apply. nginx behaves like try_files $uri $uri/ =404 with no SPA index fallback.

Friday staging on Pro receives a build with staging API URLs baked via public env prefixes. Production stays on last week’s known-good deploy until Monday’s review. Rollback remains one click if marketing’s late copy drop breaks mobile layout. Preview HTTPS is available immediately; custom-domain certificates issue only after DNS verifies.

There is a short trial (~1 day), not a forever-free tier; no cPanel, no email, no built-in CDN product.

That week is what static documentation hosting looks like when the host stays boring and the team respects file truth.

Worked example: MkDocs Material to `docs.example.com`

python -m venv .venv
source .venv/bin/activate
pip install mkdocs-material
# author docs/ and mkdocs.yml with site_url: https://docs.example.com/
mkdocs build
ls site
cd site && zip -r ../project-docs.zip .

Deploy the zip. On HTTPS preview, search for a known heading, open a deep page, hard-refresh. Confirm site_url does not still say http://127.0.0.1:8000. When preview matches the style guide, add docs.example.com, create DNS exactly as the dashboard shows, wait for verification, then confirm the certificate. Leave MX alone—StaticHost is not your mail host.

For Docusaurus, mirror the discipline with baseUrl: '/' and upload build/ contents. If a deep doc path 404s on refresh, inspect the artifact for a real HTML file before asking for an nginx exception that will not arrive.

Failure table (docs hosts)

Symptom	Likely cause	Fix
CSS theme missing	Zipped wrong folder or incomplete build	Upload `site/` or `build/` contents after a clean build
Every asset under `/project/` 404s	GitHub Pages `baseUrl` leftover	Set `baseUrl: '/'` or MkDocs site URL without subpath; rebuild
Version switcher 404	Multi-version paths not emitted	Generate `/v1/`, `/v2/` into one tree or use separate sites
Search empty	Index not built / wrong base	Rebuild search plugin assets; verify JSON 200
Staging leaked draft pages	Deployed author branch to production	Use Pro staging ($30) for “next”; promote deliberately
Private docs publicly readable	No auth layer	Treat URLs as public or put an external gate in front

Multi-version procedure on plan limits

Starter ($9, 1 site, 2 GB) suits a single docs set. Pro ($30, 3 sites, 10 GB, staging) supports production + staging + an older major version as its own site. Scale ($65, 10×30 GB) and Business ($130, 30×100 GB, teams) exist for product suites. Subpath versioning (/v1/, /v2/) keeps one site but demands generator base discipline; separate sites isolate broken experiments behind different hostnames.

CI should fail when link checkers find internal 404s—catch them before StaticHost serves them. The host will happily serve a perfect zip of imperfect docs. Rollback via deploy history when a sidebar regression escapes review. No forever-free, cPanel, email, or built-in CDN product; trial ~1 day.

FAQ

Can I host private docs?

StaticHost serves what you upload publicly to anyone with the URL unless you place an external auth layer in front. Treat URLs as public by default.

Does Docusaurus need Node on the server?

Not for static builds. Node is for local/CI build and for non-static hosting modes you are not using here.

How do I fix `/docs/foo` 404 on refresh?

Ensure the build emitted docs/foo/index.html or equivalent. SPA fallback is not available.

Should API reference live on the same site?

Yes if generated into the same output tree. Keep generators’ nav coherent.

Is MkDocs Material fine on StaticHost?

Yes—upload site/ contents after mkdocs build.