Technical Website Platform

Product specification & feature sheet

A self-hosted publishing platform that combines a fast, static documentation and blog website with a lightweight private administration layer — letting an operator manage selected content and live data without rebuilding or redeploying the site.

Product Overview

What it is

The Technical Website Platform is a self-hosted website solution built on a static site generator and packaged as a single Docker image. It serves a public website (blog, documentation, projects, static pages) and adds a small private admin layer that allows authorised users to edit selected content and live data through the browser.

The result is a website that is as fast and cheap to host as a static site, but as editable as a small CMS for the parts that change often.

Problems it solves

• Static sites are fast but rigid — editing normally means changing files and rebuilding. This platform keeps the speed of a static site while letting an operator edit chosen content (status, notes, project cards, profile, navigation text) live.
• Traditional CMS platforms are heavy — they need a database server, a runtime stack, and ongoing security maintenance. This platform uses an embedded file database and a dependency-free runtime, so the operational surface is minimal.
• Documentation and blogging are usually separate tools — here, long-form Markdown content, structured documentation, project listings and a live status board live in one deployable unit.
• Hosting cost and complexity — the entire system runs from one small container behind a standard reverse proxy.

Who it is for

• Technical teams and individuals who want a documentation + blog site they fully control.
• Operators who want live, editable widgets (status, notes, project showcase) without a build pipeline for every change.
• Organisations preferring self-hosted, low-maintenance infrastructure over SaaS.
• Anyone who values Git-based content, fast load times, and simple backups.

Architecture at a Glance

flowchart LR
  subgraph Build["Build stage (CI)"]
    MD["Markdown content (Git)"] --> SSG["Static Site Generator"]
    SSG --> HTML["Static HTML / CSS / JS"]
  end
  subgraph Runtime["Runtime container"]
    HTML --> APP["Lightweight app server"]
    APP --> DB[("Embedded file database")]
    APP --> API["JSON API /api/*"]
    APP --> ADMIN["Private admin /admin/*"]
  end
  Browser["Visitor / Operator"] -->|HTTPS| Proxy["Reverse proxy"] --> APP
  API -. live hydration .-> Browser

The site is generated once as static files, then served by a small application server that also exposes a JSON API and a login-gated admin area. Dynamic widgets on the public pages fetch their data from the API at load time, so operator edits appear immediately without a rebuild.

Core Features

Live Status Module (optional)

An optional companion process can collect live operational data — container/service states, uptime checks (ping/HTTPS), host uptime, and external API polls — and push it to the platform over an authenticated internal endpoint. The public site then renders a single status card with coloured indicators. Data ingestion is read-only and isolated from the web process. (This module is infrastructure-oriented and can be omitted for a pure content site.)

Content Management

How content is organised

• Authored content (posts, docs, projects-as-files, static pages) is written in Markdown and stored in the Git repository. It is organised into sections (folders) and enriched with front-matter metadata (title, description, tags, categories, dates).
• Dynamic content (project cards, notes, profile/about card, status widget items, navigation/footer text, theme text) is stored in the embedded database and edited through the admin area.

This split means long-form, version-controlled writing stays in Git, while frequently changing data is editable live.

How new pages are created

• Authored pages: add a Markdown file in the relevant content section with front-matter; the generator routes it automatically by section (e.g. a new article in the posts section becomes a post with the standard template).
• Managed items: create entries (a project, a note, a status line) directly in the admin forms — no file editing required.

How content is published

• Authored content is published by committing to the repository’s main branch, which triggers an automated build and deployment of the static site.
• Managed/dynamic content is published the moment it is saved in the admin — the public page hydrates the new data from the API on the next load, with no rebuild.

User Experience

• Responsive design — a two-column layout (content + sticky sidebar rail) that collapses cleanly to a single column on smaller screens.
• Dark mode — a light/dark toggle whose preference is stored in the browser and persists across pages and the admin area; the correct theme is applied before first paint to avoid flashing.
• Navigation — a fixed top navigation menu, a contextual sidebar, taxonomy chips, and previous/next links on articles.
• Search — an instant header search with a debounced live dropdown plus a full results page, powered by a full-text index.
• Readability — an editorial typography system (serif display + readable body + monospace for code), generous spacing, and a focused reading column.
• Document viewing — documentation and articles render with a table of contents, code highlighting, and rich components (see Available Components).

Available Components

Content authors can use shortcodes — reusable components embedded directly in Markdown. The platform ships custom components plus a comprehensive set inherited from the underlying theme.

Custom components

Theme components

The platform inherits a rich component library from its theme. Common ones:

Exact parameters for theme shortcodes follow the underlying theme’s conventions; verify against the theme version in use before relying on specific options (requires verification).

Technical Architecture

• Static generation — a modern static site generator builds the entire public site to plain HTML/CSS/JS at build time. There is no per-request rendering of authored content, giving excellent performance and cacheability.
• Lightweight runtime — a small application server (standard-library only, no third-party runtime dependencies) serves the static files and provides the /api/* (JSON) and /admin/* (private) routes.
• Embedded database — an embedded, file-based SQL database (write-ahead logging enabled) holds admin settings, the search index, and dynamic content. No separate database server is required.
• Containerised — the whole platform ships as a multi-stage Docker image: a build stage compiles the static site, and a minimal runtime stage serves it.
• Performance — static delivery, a small runtime footprint, asset fingerprinting and minification, and client-side hydration only for the few dynamic widgets.
• Security
  • Login-gated admin; the public site never exposes editing endpoints.
  • Password hashing with a strong key-derivation function, per-user salt, and a high iteration count.
  • Session cookies are HTTP-only and same-site, with a bounded lifetime.
  • CSRF protection on every state-changing admin request.
  • Login rate limiting to slow brute-force attempts.
  • Upload validation (type/size) with server-generated filenames.
  • For the optional status module, infrastructure access is read-only and isolated — the web process never receives privileged host access.
• Authentication — supported (see Core Features); single administrator by default.

sequenceDiagram
  participant V as Visitor
  participant P as Reverse proxy
  participant A as App server
  participant D as Embedded DB
  V->>P: HTTPS request
  P->>A: Forward
  A-->>V: Static HTML (prebuilt)
  V->>A: GET /api/sidebar (hydration)
  A->>D: Read dynamic data
  D-->>A: Rows
  A-->>V: JSON (live widgets)

Deployment

• Docker image — a single image contains the built static site and the runtime server. Versioned image tags support rollback to any previous build.
• Container setup — deployed via container orchestration (e.g. Docker Compose). A typical stack is:
  • the web container (site + API + admin),
  • an optional collector container (live status module),
  • an optional read-only socket proxy (isolating infrastructure access for the collector).
• Configuration — environment variables and an optional environment file control optional settings (e.g. network name, integration tokens). Sensible defaults mean the platform runs with minimal configuration; the initial admin credential is seeded on first run and should be changed immediately.
• Reverse proxy — the container is published behind a standard reverse proxy for TLS and host routing.
• Persistent data — the database and uploaded media live on a mounted volume (or host bind mount), so they survive redeployments.
• Update process — pulling a new image and recreating the container deploys a new build; the persistent volume keeps all dynamic data and media intact. Schema changes are applied idempotently on start-up.

Content Workflow

flowchart LR
  Author["Author writes Markdown"] --> Git["Commit to Git (main)"]
  Git --> CI["CI pipeline"]
  CI --> Build["Static build + image"]
  Build --> Registry["Container registry"]
  Registry --> Deploy["Recreate container"]
  Deploy --> Live["Public site"]
  Operator["Operator edits in /admin"] -->|saved instantly| DBlive[("Embedded DB")]
  DBlive -. live hydration .-> Live

• Git-based content — authored content is plain Markdown in version control, giving full history, review, and rollback.
• Automatic generation — committing to the main branch triggers an automated build of the static site and a new container image.
• Publishing — the new image is deployed automatically; static content goes live with the deployment.
• Updates — dynamic content (managed in the admin) updates instantly without a rebuild, while authored content updates flow through the Git → build → deploy pipeline.

Benefits

• Low resource usage — a single small container; no database server, no heavy runtime.
• Simple operations — minimal moving parts, dependency-free runtime, idempotent start-up migrations.
• Fast load times — pre-built static delivery with minified, fingerprinted assets.
• Easy backup — content is in Git; dynamic data and media are a single volume to snapshot.
• Easy version control — all authored content is Git-tracked with full history.
• Easy scaling — stateless static delivery scales horizontally behind a proxy/CDN; the small runtime can be replicated.
• No rebuild for live data — frequently changing widgets are edited in-browser and appear immediately.
• Self-hosted & portable — runs anywhere Docker runs; no SaaS lock-in.

Technical Specifications

Product Screenshots

This document describes the platform generically as a product. Items marked “requires verification” depend on configuration or theme version and should be confirmed against the specific deployment before being represented to a customer.