Home / Getting Started / Publishing to GitLab Pages

Publishing to GitLab Pages

GitLab Pages serves static sites, but unlike GitHub it doesn't run a site generator for you — it publishes whatever a CI job leaves in a public/ artifact. That suits Wikidown fine: wikidown export-html renders the wiki to finished HTML in one CI job, exactly as the GitHub workflow does (see Publishing to GitHub Pages for the GitHub story and the full export-html reference).

Steps

1. (Optional) Add a _config.yml to the wiki root for the site title and other settings, and theme files if you want to customize them. wikidown pages --theme writes both; it also writes a GitHub Actions workflow, .github/workflows/pages.yml, which you can delete. export-html works without any of this, using the built-in theme.

2. Add .gitlab-ci.yml at the repo root:

   pages:
     image: mcr.microsoft.com/dotnet/sdk:10.0
     stage: deploy
     script:
       - dotnet tool install -g Wikidown.Cli
       - export PATH="$PATH:$HOME/.dotnet/tools"
       - wikidown export-html --output public --base-url "/$CI_PROJECT_NAME" --clean
     artifacts:
       paths:
         - public
     rules:
       - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
   

   The job must be named pages and the artifact folder must be public — both are GitLab conventions.

3. Push. Deploy → Pages in the project shows the URL once the job finishes — https://<group>.gitlab.io/<project>/ by default. Pages must be enabled on the instance (it is on gitlab.com).

--base-url

Project sites are served under /<project>/, and the theme's own links (stylesheet, nav, root redirect) need that prefix — --base-url "/$CI_PROJECT_NAME" supplies it. Drop the flag if the project uses a custom domain or a group-level site served from /. Links inside page bodies are relative and never need it.

Notes

• The CI container runs .NET, so nothing is installed on your machine — same as the GitHub path.
• wikidown.exclude_from_site, favicon, title, and the other _config.yml settings are honored — see Publishing to GitHub Pages for what each does.
• The same three-line script works for any CI that deploys a static folder: Azure Static Web Apps, Netlify, Cloudflare Pages, S3.
• Want a custom _layouts/wikidown.html/assets/wikidown.css or a hand-authored root index.html instead of the stock redirect? Same files, same rules as on GitHub — see Customizing the Theme.

See CLI for the full export-html option reference.