Skip to content

Hosting and sharing

The documentation is a static website: after mkdocs build, the entire deployable site is in site. It needs no database or permanent Python server.

Current deployment

The bilingual site is published at:

https://bibliotheque-vhdl-basys3.pages.dev/

Its source repository is private. Only the generated static files are public. On the configured Windows computer, deploy-cloudflare.cmd performs a strict build and publishes the result.

Public-source option: GitHub Pages

For a public personal library, GitHub Pages keeps the source and website in one service.

  1. Create a new public GitHub repository.
  2. Push this project to its main branch.
  3. Open Settings → Pages in the repository.
  4. Under Build and deployment, select GitHub Actions as the source.
  5. Open the Actions tab and wait for Deploy bilingual MkDocs site to finish.

The generated links are relative, so both languages also work when the site is hosted below username.github.io/repository.

GitHub Pages is available for public repositories on GitHub Free. The deployed website is public and served over HTTPS.

Selected for this library: Cloudflare Pages

Cloudflare Pages is used for this library because it can connect to a private source repository while publishing only the generated site:

  • Free plan with up to 500 builds per month.
  • Automatic HTTPS and a pages.dev address.
  • Correct root-level paths for the English/French switcher.
  • Automatic rebuild after each Git push.
  • Optional custom domain later.

One-time setup

  1. Create a GitHub repository and push this project.
  2. In Cloudflare, open Workers & Pages → Create application → Pages.
  3. Select Import an existing Git repository.
  4. Choose the documentation repository.
  5. Configure:
Setting Value
Production branch main
Build command mkdocs build --strict
Build output directory site
Python version A currently supported Python 3 release

The checked-in requirements.txt installs MkDocs, Material, and the bilingual plugin. After deployment, Cloudflare provides an address similar to:

https://vhdl-basys3-library.pages.dev

Every push to main rebuilds and publishes the site.

Netlify

Netlify is the quickest manual demonstration:

  1. Build locally with build-docs.cmd.
  2. Sign in to Netlify.
  3. Drag the generated site directory into the deployment interface.

It provides a public HTTPS address immediately. Git-based automatic deployment is also available; netlify.toml already contains the build settings.

The current free plan uses monthly credits and pauses sites when the allowance is exhausted. This is unlikely for a small personal handbook, but Cloudflare Pages has a simpler limit model for this use case.

Share without an account

For offline sharing:

  1. Run build-docs.cmd.
  2. Zip the entire site directory.
  3. Send the archive.
  4. The recipient can extract it and open index.html.

Hosting the directory through a static web server gives the most reliable search and navigation behavior.

Before publishing

  • Remove personal or confidential material.
  • Run mkdocs build --strict.
  • Test English and French versions.
  • Test the language switch on a nested page.
  • Test search in both languages.
  • Verify mobile and dark-mode layouts.
  • Confirm all source licenses and external links.
  • Remember that the published site is public unless the host is configured otherwise.