[!WARNING] Preview release (0.x). This package is under active development. The public API (CLI commands, exported functions, template structure, and config shape) may change between minor versions until the 1.0.0 release. Pin an exact version in production ("@techfides/tf-doc-vault": "0.1.5", not "^0.1.5") and review the CHANGELOG before upgrading.

Why this package exists

Every documentation project needs a similar boilerplate: a VitePress configuration, a versioned sidebar, shared UI components, a CI workflow, and a deploy target. Setting all of that up from scratch for each project takes long time and produces subtly divergent configurations that are hard to maintain.

@techfides/tf-doc-vault solves this once and shares the solution across all projects. The core idea is factory functions over copied files: consumer repos call makeConfig() and createTheme(); the package owns the implementation, so updates propagate automatically.

What the package includes

| Module | Purpose | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | config | makeConfig(): complete VitePress config with locales, versioned nav, sidebar, i18n, Mermaid, optional analytics and edit links. | | theme | createTheme(): the backdrop, DocMeta, footer, lightbox and table behaviour, plus BrandHero, FeatureCards, Spotlight and AuthorCard for Markdown. | | sidebar | Auto-generates nav and sidebar from the docs/<version>/<section>/<group>/ directory structure, with no manual config. | | scripts | CLI commands: validate, normalize, build print page, export to PDF, fix line endings, sync boilerplate. | | configs | Shared eslint.config.js, prettier.json, tsconfig.base.json for consumer repos to extend. | | infra/terraform | Reusable GCP module: Cloud Run + Artifact Registry + IAM, optional IAP (iap_enabled). | | docker | Multi-stage Dockerfile with nginx / nginx-auth runtime variants. | | boilerplate | The VitePress project scaffold shared by every template: config, theme wiring, GitHub Actions CI, Vercel config, auth middleware, .gitattributes. | | templates | Markdown content sets (ana-docs, tech-docs, …), one folder per template, selected via tf-doc-vault setup --template=<name>. |

Quick start

You don't wire this up by hand. Run the interactive wizard and pick a template:

pnpm dlx @techfides/tf-doc-vault@latest setup

It asks which template to use, then prompts for the fields that template needs. Non-interactively (CI, scripts), pass --template and the required flags and it never prompts:

• Standalone analysis / spec site (its own repo, deployed to Vercel via git integration):

  pnpm dlx @techfides/tf-doc-vault@latest setup my_analysis --template=ana-docs

  Full guide → Analytical documentation

• Docs inside an existing service (published by the service repo's own pipeline):

  pnpm dlx @techfides/tf-doc-vault@latest setup --template=tech-docs --service-id=TST --project=my-service

  Full guide → Technical documentation

• Migrating from Confluence? → Import from Confluence

Adding a template of your own means adding a folder under templates/<name>/ with a _template.md manifest (target location, fields to prompt for, which boilerplate files to exclude): no code change, the wizard lists it automatically.

Configuration

Scaffolding generates the VitePress wiring for you. To customize a site afterwards, edit the two factory calls it writes:

docs/.vitepress/config.ts

import { makeConfig } from "@techfides/tf-doc-vault/config";

export default makeConfig({
  configDir: import.meta.dirname,
  project: "lapa",
  // optional: analytics, editLink, branding, sectionNav, mermaid, toBeTags, …
  analytics: { provider: "umami", websiteId: "...", domain: "..." },
  editLink: { repo: "TechFides/tf-sales-private-offers", branch: "main" },
});

docs/.vitepress/theme/index.ts

import { createTheme } from "@techfides/tf-doc-vault/theme";
import "./custom.css"; // overrides on top of base CSS

export default createTheme({ widthToggle: true });

Installing via a git URL? Add "pnpm": { "onlyBuiltDependencies": ["@techfides/tf-doc-vault"] } to the consumer package.json, or pnpm 10 skips the prepare hook and dist/ is never built. (The scaffolders already set this for you.)

To rebrand (colors, logo, fonts, footer) for a non-TechFides project, see BRANDING.md.

Layout without versions

Every folder in docs/ is a documentation version by default (docs/v1/…, served under /v1/). A repo whose docs/ tree has to keep its paths, because other tools read it, turns that off in tf-doc-vault.json next to the docs/ folder:

{ "versioned": false }

docs/ then plays the role of the version folder: its subfolders are the sections in the navbar, pages are served without a version segment (/process/…), and docs/index.md opens the sidebar and the PDF. The site config, validate, normalize and print all read the setting from that file. Any key other than pdf and versioned prints a warning that names it, so a misspelt Versioned does not quietly keep the versioned layout.

PDF export

tf-doc-vault pdf builds the site and renders /print into artifacts/. With no further setup it produces docs-full.pdf: every page in sidebar order, a contents list with page numbers, bookmarks that mirror the sidebar, and a running footer.

A project that sends its PDF to a customer adds tf-doc-vault.json in its root to get a cover page and a letterhead:

{
  "pdf": {
    "fileName": "TechFides-nabidka-acme.pdf",
    "mark": "TechFides",
    "footerLabel": "Nabídka pro Acme",
    "cover": {
      "eyebrow": "Návrh spolupráce pro Acme",
      "title": "Název nabídky",
      "subtitle": "Jedna věta o tom, co nabídka řeší.",
      "vendor": "TechFides Solutions s.r.o.",
      "website": "techfides.cz",
      "recipient": "Acme",
      "validUntil": "30. září 2026",
      "contact": "Jméno · e-mail",
      "confidentiality": "Důvěrné."
    }
  }
}

Only cover.title is required; every other row is left off the imprint when it is not set. fileName is a name, not a path: the PDF always lands in artifacts/. Design notes and limits are in specs/pdf-export.md.

Documentation

Task-focused guides live in docs/:

| Guide | What it covers | | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Technical documentation (tech-docs) | Docs living inside a service repo, scaffolded via setup --template=tech-docs; the service repo publishes them itself. | | Analytical documentation (*_ana) | Standalone analysis docs scaffolded via setup --template=ana-docs, deployed to Vercel, including the auth middleware and syncing the boilerplate. | | Import from Confluence | Migrate a Confluence space into Markdown (import-confluence). | | Editing & publishing docs | The day-to-day edit → preview → validate → publish loop. | | Testing | How the package itself is tested (unit + smoke). | | Migrations | Breaking-change guides for major package versions. |

Migrations

Breaking-change guides for major package versions are in docs/MIGRATIONS.md.

Contributing & local development

Setup, the playground hot-reload workflow, the file:-consumer flow, and the release process are in CONTRIBUTING.md.

Changelog

See CHANGELOG.md for release notes.