Skip to content

Release Notes

cal-docs-server 3.2.2 - 13 Apr 2026

Fixed

  • GitLab Pages mode: new version directories could be missed by incremental polling when GitLab bumped updated_at for a push but left last_activity_at unchanged (observed in practice on gitlab.com). Change detection now keys on max(last_activity_at, updated_at), so either field moving triggers a per-project rebuild

Added

  • GitLab Pages mode: a full rescan now runs automatically every 24 hours as a safety net, so anything missed by incremental polling — including projects removed and re-added, or index state drift — is reconciled daily without a server restart

cal-docs-server 3.2.1 - 13 Apr 2026

Fixed

  • Download zips now extract with correct permissions (0644 for files, 0755 for directories). Previously external_attr was left unset, which unzip on macOS/Linux interpreted as mode 0, producing unreadable/untraversable files and directories. Affects both GitLab Pages mode (_repack_zip) and filesystem mode (create_docs_zip); filesystem mode also now emits explicit directory entries

cal-docs-server 3.2.0 - 12 Apr 2026

Added

  • GET /api/projectlist — lightweight project list returning name, slug, description, version count, and URL. No version details or logos. Supports ?search=
  • GET /api/project/{project} — detailed info for a single project including versions. Logo excluded by default; pass ?logo=1 to include it
  • API version bumped to 1.1

Fixed

  • GitLab Pages mode: download_url in /api/projects was blank for all GitLab-sourced projects; now correctly populated
  • download_url in API responses now uses the convenient download URL format (/{project}-{version}-docs.zip) instead of the API endpoint path, and is always absolute — falling back to the request origin when base_url is not configured. The request origin honors X-Forwarded-Proto / X-Forwarded-Host so the correct public scheme (e.g. https) is used behind a reverse proxy
  • GitLab Pages mode: projects pending deletion on GitLab (which remain in the group API for up to a month) are now filtered out so they disappear from the index immediately
  • Beta/Dev ribbon is now rendered server-side, eliminating a visual pop-in on page load
  • Convenient zip download URL parser (/{project}-{version}-docs.zip) now looks up project slugs from the index instead of regex-guessing, so versions containing a hyphen followed by a non-digit (e.g. 1.2.3-abc1234 git hashes) resolve correctly
  • GitLab Pages mode (toggle): API endpoints (/api/projects, /api/project/{project}, /api/projectlist) now return this server's proxy URL ({origin}/{slug}/{version}/) for the url field whenever proxying is enabled, instead of the raw GitLab Pages subdomain. API clients get a single reliable URL on the docs server; the HTML-page direct/proxy toggle is unaffected

Changed

  • GitLab Pages mode: when polling fails with a 401/403 (revoked or expired token), the cached project state is cleared so the index stops advertising projects the server can no longer serve. Cached state repopulates on the next successful poll
  • GitLab Pages proxy: upstream errors other than 404 are now translated to 502 Bad Gateway instead of being passed through. Stops a bare upstream 401 from being mirrored to end users (and from being rewritten by intermediaries like nginx)

cal-docs-server 3.1.0 - 24 Mar 2026

Added

  • GitLab Pages source mode: index documentation hosted on GitLab Pages instead of a local filesystem directory, using the GitLab API to scan groups and build the index
  • Configure via --gitlab-group / --gitlab-token CLI options or config file
  • Multiple groups supported via gitlab_groups list in config, each with its own token
  • Groups are scanned in parallel and their indexes are merged and sorted
  • Efficient polling: compares last_activity_at per project — one API call per interval in steady state; only changed projects are re-indexed
  • Resolves unique GitLab Pages domains (e.g. project-abc123.gitlab.io) via GET /projects/:id/pages so links bypass the group-URL redirect chain
  • Logos fetched via the GitLab API and embedded as data URIs (works with private Pages)
  • Supports docinfo.json, docinfo.json5, docinfo.yml, docinfo.yaml — same formats as filesystem mode
  • "Scanning in progress" placeholder page served during initial startup scan, with auto-refresh and matching dark colour scheme; web server accepts connections immediately without waiting for the scan to complete
  • Download endpoints work in GitLab Pages mode: server fetches the repository archive from GitLab and repacks it as a zip; latest resolves to the actual version name in the Content-Disposition header
  • Upload and delete endpoints return 405 in GitLab Pages mode
  • Progress logging during initial scan: [1/N] scanning project-name
  • GitLab Pages proxy mode (gitlab_proxy config option or --gitlab-proxy CLI flag): proxies all documentation content through the server instead of linking directly to GitLab Pages URLs. Fetches files via the GitLab repository API so it works with private Pages that require authentication. The gitlab_proxy option is a string with five values:
  • "off" (default) — direct links on index; proxy URLs still work if accessed directly
  • "always" — all index links proxied through the server (--gitlab-proxy CLI shorthand)
  • "toggle" — adds a UI toggle switch so users can choose between direct and proxied links, with the preference persisted in localStorage (defaults to direct)
  • "toggle-on" — same as "toggle" but defaults to proxied
  • "disabled" — proxy completely off; proxy URLs return 404
  • Configurable group labels with hex colour on index tiles (GitLab Pages mode)
  • --help-config CLI flag: prints a full description of the config file format and exits
  • gitlab_poll_seconds config key (replaces gitlab_poll_interval_seconds; old key still accepted for backwards compatibility)

cal-docs-server 3.0.0 - 7 Mar 2026

Added

  • REST API for programmatic access to documentation:
  • GET /api/version - Returns product name, version, and API version
  • GET /api/spec - Returns OpenAPI 3.0 specification
  • GET /api/projects - Lists all projects and versions (supports ?search= filter)
  • GET /api/download/{project}/{version} - Download project as zip file
  • POST /api/upload - Upload documentation zip file (requires authentication)
  • DELETE /api/delete/{project}/{version} - Delete a specific documentation version
  • GET /api/help - Human-readable API documentation
  • Convenient download URLs: /{project}-{version}-docs.zip and /{project}-latest-docs.zip
  • Token-based authentication for protected endpoints via --tokens CLI option
  • Supports per-token project restrictions
  • Supports allow_overwrite permission to update existing versions
  • Supports allow_delete permission (defaults to false)
  • Supports existing_projects_only to restrict to existing projects
  • Tokens are dynamically reloaded (5 second cache) — no restart required
  • Configuration file support via --config option (default: ~/.config/cal-docs-server/config.json)
  • --base-url option for API response URLs
  • --license flag to display the full MIT license text
  • MIT License
  • Works with cal-docs-client CLI tool for easier API access

Changed

  • --version output standardised to name: VERSION / python: X.Y.Z format
  • --help output now includes version and copyright notice
  • Upload size limit removed (was 1 MB aiohttp default, now unlimited)
  • Improved error handling throughout to prevent server crashes
  • Now requires Python 3.12+

cal-docs-server 2.1.0 - 16 Dec 2025

  • Added live search filter to index page. Search filters projects by title as you type. No backend required - all client-side JavaScript

cal-docs-server 2.0.0 - 8 Dec 2025

  • All new designed theme. Does not use Materialize.

  • Requires Python 3.12+

  • Builds using UV and makefile. Produces a .whl

cal-docs-server 1.4.0 - 10 Jul 2025

  • Dark theme

  • Versions are now in collapsible sections

cal-docs-server 1.3.0 - 3 May 2024

  • Versioned directories can be suppressed if they have noindex=True in their docinfo

  • If a file docinfo.png, docinfo.jpg, or docinfo.svg is next to the main docinfo.json file then it will used as a logo to include on the index page

cal-docs-server 1.2.0 - 6 Mar 2024

  • Order of versions sorted properly

  • Removed dependency on pypi package aiofiles

cal-docs-server 1.1.0 - 4 Mar 2024

  • Now can render .md files by dynamically converting markdown to html.

  • Added "help" link on nav bar which links to help documentation.

  • Caches the template file for the index.

cal-docs-server 1.0.0 - 3 Mar 2024

  • First release