MarkdownEngine

Lore — A documentation site generator for teams that store documentation as Markdown in a Git repository.

What Is Lore

Lore renders Markdown files into a browsable, searchable static website and integrates with GitLab CI to automate publishing and generate per-MR preview deployments on Kubernetes.

Core Value: A single lore build command turns a Markdown repository into a production-ready documentation site — no server, no database, no maintenance.

Features

• lore build — Walk a docs repo, render all .md files to HTML, copy image assets, write to ./dist/
• lore build --incremental — Hash-based manifest; only re-render changed files
• lore serve — Full build + file watcher + local HTTP server on :4000 with live reload
• YAML front matter — title, order, draft, description fields
• Navigation tree — Built from directory hierarchy + front matter ordering
• Per-page Table of Contents — Auto-generated from h2/h3 headings, sticky on scroll
• Full-text search — Pagefind (static WASM+index, no server needed), Cmd+K trigger
• Syntax highlighting — chroma, goldmark-native integration
• 3-column site layout — Left nav sidebar, content, right ToC; Tailwind CSS styling

Quick Start

# Build a docs directory into ./dist/
lore build ./docs

# Serve locally with live reload at http://localhost:4000
lore serve ./docs

# Incremental build (only re-renders changed files)
lore build --incremental ./docs

CI/CD Integration

Lore includes a reusable GitLab CI component that automates the full documentation pipeline:

# Add to your team's .gitlab-ci.yml
include:
  - project: 'internal/lore'
    ref: main
    file: '.gitlab/ci/lore.yml'

What the pipeline does:

• Build — Runs lore build --incremental, producing a dist/ artifact (only changed files re-rendered)
• Package — Builds a Docker image tagged with the commit SHA and pushes it to the GitLab Container Registry
• Deploy (main branch) — Updates the production site by committing a new image tag to a FluxCD config repo
• Deploy (merge requests) — Creates a preview deployment at https://mr-{IID}.docs.example.com, surfaced as a GitLab Review Apps "View app" button on the MR page
• Teardown (auto) — Merging or closing the MR deletes the preview; FluxCD removes the namespace from the cluster within 1 minute
• Teardown (manual) — A manual cleanup job is available on any MR pipeline run

Infrastructure components:

Getting started:

• Team onboarding guide — add the CI component to your project
• Operator setup guide — configure the cluster and GitLab-side prerequisites

Requirements: Kubernetes cluster with Traefik ingress + cert-manager + FluxCD, Cloudflare DNS for wildcard TLS.

Tech Stack

License

See LICENSE for details.