This repository builds the static BlogVault documentation portal. General product help is published at the site root; the versioned developer API is published below /api/.
OpenAPI is the authoritative source for API paths, schemas, parameters, responses, and examples. Markdown provides the human-written workflow and product guidance around that contract.
.
├── docs.config.json # Site, API base path, versions, and navigation
├── v6/
│ ├── openapi.yaml # Modular OpenAPI root document
│ ├── paths/ # Endpoint definitions
│ ├── components/ # Schemas, responses, examples, and errors
│ └── shared/ # Reusable OpenAPI parameters and schemas
├── content/
│ ├── docs/ # General documentation landing pages
│ ├── articles/ # Imported Freshdesk categories and articles
│ ├── assets/knowledge-base/ # Local copies of article images
│ ├── shared/ # API pages reused by every API version
│ └── v6/ # API v6 guides, overview, and changelog
├── site/assets/ # Logo, CSS, browser scripts, and Scalar loader
├── scripts/ # Importer, build stages, and validation
└── dist/ # Generated Cloudflare deployment output
There is one editable representation of each API definition. v6/openapi.yaml references the modular files below v6/; the build validates and bundles them into a self-contained JSON document. Do not edit dist/ by hand.
The Freshdesk importer is maintained at scripts/import-freshdesk.mjs. It crawls the public Solutions folders, creates clean category/article routes, downloads article images into content/assets/knowledge-base/, and writes the article source URL and ID into front matter for provenance.
npm ci
npm run check
npm run build
npm run preview
Then open http://localhost:8787/. The preview serves the generated dist/ directory, including article pages, local images, Scalar, OpenAPI JSON, search, redirects, and 404 handling.
To refresh the Freshdesk import after source articles change:
node scripts/import-freshdesk.mjs
npm run check
npm run build
The importer is intentionally network-dependent. The generated Markdown and downloaded images are committed as documentation source so deployments do not need Freshdesk access.
/ General documentation home
/staging/ Freshdesk category landing page
/staging/delete-a-staging-site/ Clean imported article URL
/api/ Redirects to the latest API version
/api/v6/ API v6 documentation home
/api/v6/reference/ Scalar interactive API reference
/api/v6/reference/tag/sites/list-sites/ Stable operation page
/api/v6/resources/sites/ API resource overview
/api/v6/openapi.json Bundled authoritative OpenAPI document
/api/v6/api.md Compact generated API reference
/api/v6/llms.txt Agent-oriented API index
/api/v6/llms-full.txt Full generated API context
Article URLs are derived from the Freshdesk category and article title. For example, the source article 25000034747-how-do-i-delete-a-staging-site- is published as /staging/delete-a-staging-site/. The route is stored in the article front matter and does not depend on the display title after import.
The root search index covers general articles and API pages. Each API version also has a version-local search.json. The build emits sitemap.xml, robots.txt, canonical metadata, Open Graph metadata, and a build manifest.
Freshdesk’s original folders are treated as import metadata, not as the public information architecture. The maintained routing rules are in scripts/freshdesk-taxonomy.mjs, and the importer regenerates both article URLs and category landing pages from those rules.
Account /account/
Billing /billing/
Clients /clients/
Teams /teams/
Integrations /integrations/
White label /whitelabel/
Site /site/
Connection /site/connection/
Updates /site/updates/
Activity logs /site/activity-logs/
Security /security/
Firewall /security/firewall/
Scanner /security/scanner/
Geoblocking /security/geoblocking/
Vulnerability Shield /security/vulnerability-shield/
Staging /staging/
Backups /backups/
Migration /migration/
Monitoring /monitoring/
Reports /reports/
Affiliate /affiliate/
AirLift /airlift/
Scan articles are placed under Security → Scanner. Firewall, geoblocking, vulnerability, billing, connection, update, white-label, client, and team articles are split into their respective product areas. The original Freshdesk folder, source URL, and source ID remain in article metadata for traceability.
npm run build performs these stages:
v<number>/openapi.yaml into dist/api/<version>/openapi.json./api/<version>/./api/<version>/reference/./.dist/assets/.api.md, llms.txt, llms-full.txt, headers, redirects, sitemap, and 404 output.Scalar is pinned in package.json, copied into the generated asset directory, and loads the versioned OpenAPI JSON as a separate static resource. It does not persist authentication credentials.
Add a new modular source tree beside v6/:
v7/
├── openapi.yaml
├── paths/
├── components/
└── shared/
Add v7 to docs.config.json and set latest to v7 only when it is ready to publish. The build will then publish /api/v7/, keep /api/v6/ available, show the API version selector, and update the root /api/ alias to the configured latest stable version. Do not reuse a version URL for a materially different API.
The web-host/platform API is not published yet. When it is ready, keep it as a separate API family with its own OpenAPI source rather than mixing its paths and schemas into BlogVault API v6/v7:
platform/
└── v1/
├── openapi.yaml
├── paths/
├── components/
└── shared/
The future build should bundle that source independently and publish it at:
/platform/ Redirect to the latest stable Platform API
/platform/v1/ Platform API v1 documentation home
/platform/v1/reference/ Platform Scalar reference
/platform/v1/openapi.json
Platform navigation, guides, search entries, version selection, machine-readable outputs, and release status should remain distinct from /api/v6/ and /api/v7/. The site shell and branding can be shared, but the OpenAPI documents, tags, operation IDs, examples, and API version lifecycles must remain separate. This keeps a future platform API from exposing unrelated resources in the main BlogVault API reference.
wrangler.jsonc serves only dist/ as static assets. Run npm run build before npm run deploy:
npm run build
npm run deploy
Generated headers provide security headers, correct content types and caching for machine-readable files, and immutable caching for static assets. Missing pages are real 404s rather than silently falling back to the documentation home.