HOW IT WORKS
A website is a content repository plus a standard image
The engine ships as a builder image with the framework and its dependencies already installed. Your repository holds content and a few lines of Dockerfile — no toolchain, no node_modules, no build configuration to maintain. CI turns the two into a static site and bakes it into an nginx image.
Two builder images, two kinds of website
Pick the image that matches what you are publishing. Everything else — the markdown pipeline, image optimization, SEO files, caching rules — is inherited from it.
{project}/docsKnowledge bases
The markdown files your team already writes in GitLab, published as a website. Clients read the site instead of walking into your repository.
- Plain .md and .mdx files, no front matter required
- README.md becomes the site root, links between .md files are rewritten into slugs
- Optional intranet mode behind basic auth
{project}/wwwLanding pages
Marketing sites with strictly typed content: the structure is fixed, the copy changes often — and changing it never touches the layout.
- Content written as semantic typed tags in MDX
- Images, PDFs and other assets served straight from the repository
- A single pages.config.js per site: title, contacts, logo, locales, menu
What happens on push
The same four steps for every site produced by the technology — nothing bespoke per project.
- 1
Content lands in git
You edit markdown or typed content tags — in your IDE, in the GitLab web editor, or with an AI agent working on the repository
- 2
CI pulls the builder
A standard pipeline pulls the builder image; the engine and its locked dependencies come ready-made, so builds stay reproducible for years
- 3
Static output is built
Markdown is rendered, images are converted into responsive webp, files are pre-compressed and SEO files are generated
- 4
An image ships
The result is an ordinary ~50 MB nginx image — deploy it to our Kubernetes clusters or to any Docker hosting you control
The whole build configuration of a site
This is not an excerpt — a content repository really is this small. The image paths are a public contract: they do not move under your feet.
Knowledge base
A repository of markdown files becomes a documentation site.
FROM h.gitt.one/pages/engine-astro/builder-docs:latest AS builder
RUN rm -rf src/content/docs/*
COPY . src/content/docs/
COPY pages.config.js ./
RUN pnpm run build
FROM h.gitt.one/commons/nginx-basicauth:master AS runner
COPY --from=builder /src/apps/docs/dist /usr/share/nginx/htmlPlus a three-line .gitlab-ci.yml and pages.config.js with the site title and URL.
Landing page
Content, images and assets are copied over the examples shipped in the image.
FROM h.gitt.one/pages/engine-astro/builder-www:latest AS builder
RUN rm -rf src/articles/* src/images/*
COPY articles/ src/articles/
COPY images/ src/images/
COPY pages.config.js ./
RUN pnpm run build
FROM h.gitt.one/pages/engine-astro/nginx:latest
COPY --from=builder /src/apps/www/dist /usr/share/nginx/htmlThe runner image already serves with compression, caching rules and a 404 page — nothing to configure.
THE QUALITY BAR
What every produced site gets
Not a per-project checklist to negotiate — these come from the builder image, so the newest site is as good as the best one.
- Lighthouse 100
- Performance, accessibility, best practices and SEO — the acceptance target for every site, measured on production
- Zero JavaScript by default
- Pages are plain pre-rendered markup; interactive pieces ship as small islands, so a contact form costs about a kilobyte
- Images done properly
- Responsive variants converted to webp at build time, with priority hints on the ones that decide your loading score
- Pre-compressed delivery
- Static files are compressed during the build and served ready-made by nginx, with immutable caching for hashed assets
- SEO out of the box
- Sitemap, robots.txt, per-page meta tags, favicon set and heading anchors that behave exactly like GitLab's
- Markdown that matches GitLab
- One rendering engine everywhere: tables, task lists, footnotes, syntax highlighting, Mermaid and PlantUML diagrams
- Cookieless analytics
- Self-hosted, privacy-preserving statistics by default — no cookies, and therefore no consent banner in your visitors' way
- Contact forms with spam protection
- A native HTML form, a lightweight challenge instead of a heavy captcha, and visible feedback when the message is sent
- Content validated at build time
- Typed content schemas and linting run in CI, so a broken link or a missing field fails the pipeline, not the visitor
EXIT STRATEGY
Designed so you can leave
You own the content: semantic MDX files are not tied to our engine and migrate into any CMS. The engine itself is Astro — the most widely used content framework, MIT-licensed — so any developer or AI agent can pick the project up. We measure this honestly as exit time: minutes from git clone to a working local build for a developer who has never seen the project.