Skip to content

README.md

Latest commit

 

History

History
118 lines (87 loc) · 7.92 KB

README.md

File metadata and controls

118 lines (87 loc) · 7.92 KB
Raw

HyperFormula documentation

HyperFormula comes with a dedicated, regularly-updated documentation portal.

View the documentation's latest production version at https://handsontable.com/docs/hyperformula.

About HyperFormula documentation

The HyperFormula documentation is built with VuePress, a Vue-powered Static Site Generator.

When editing the docs, you can use features described here.

Getting started with HyperFormula documentation

To start a local HyperFormula docs server:

  1. Make sure you're running Node.js 14+.
  2. From the main hyperformula directory, install the docs dependencies: 
    npm install
  3. From the main hyperformula directory, build HyperFormula: 
    npm run bundle-all
  4. From the main hyperformula directory, create a dev build of the docs and start your local docs server: 
    npm run docs:dev
  5. In your browser, go to: http://localhost:8080/hyperformula/.

HyperFormula documentation npm scripts

From the hyperformula directory, you can run the following npm scripts:

  • npm run docs:dev - Starts a local docs server at http://localhost:8080/hyperformula/.
  • npm run docs:build - Builds the docs output into /docs/.vuepress/dist.
  • npm run docs:generate-function-docs - Regenerates the built-in functions guide page from the function metadata API. Runs automatically as the first step of docs:dev and docs:build.

Deployment

The documentation site is deployed to Cloudflare Workers as the hyperformula-docs Worker in the Handsontable account (15111272c53ed0aaf84a908f0c9c7f8b). Deployments are driven by Workers Builds, the Git integration configured on the Cloudflare side — the repository holds no deployment workflow, API token, or account secret.

Trigger Command run by Workers Builds Result
push to master npx wrangler deploy production deployment
push to any other branch, and every pull request npx wrangler versions upload preview deployment at https://<branch>-hyperformula-docs.handsoncode.workers.dev, posted as a pull request comment

Configuration in the repository:

  • wrangler.jsonc — Worker name, asset directory, and asset routing.
  • worker/index.js — resolves directory and extensionless URLs and serves the 404 page, so that the URL behaviour matches the previous hosting.
  • docs/.vuepress/cf/_headers, docs/.vuepress/cf/_redirects — asset headers and redirects, copied into the root of the build output by script/prepare-cf-assets.js.
  • .nvmrc — Node.js version used by the build.

The asset directory is docs/.vuepress/dist, while VuePress writes to docs/.vuepress/dist/docs (see docs/.vuepress/build.config.js). This keeps the /docs/ prefix that every document is built with, so the site is served under https://hyperformula.handsontable.com/docs/.

Production traffic reaches this Worker through the hyperformula-website Worker, which proxies /docs* to https://hyperformula-docs.handsoncode.workers.dev (the DOCS_ORIGIN constant in that project).

Build settings in the Cloudflare dashboard, under Workers & Pages > hyperformula-docs > Settings > Build: build command npm run docs:build:cf, deploy command npx wrangler deploy, non-production branch deploy command npx wrangler versions upload, production branch master, non-production branch builds enabled.

Deploying by hand is only needed for debugging; regular deployments go through Workers Builds.

npm run docs:build:cf     # build the documentation and prepare the asset directory
npx wrangler dev          # serve the built site locally at http://localhost:8787
npm run docs:preview:cf   # upload a preview version (does not touch production)
npm run docs:deploy:cf    # deploy to production

When changing the asset routing, verify it with browser navigation headers, not plain requests: curl -H "Sec-Fetch-Mode: navigate" -H "Sec-Fetch-Dest: document". The asset router treats navigation requests differently from other requests, so a plain curl check can pass while browsers get a 404.

Built-in functions guide page

The built-in functions guide page docs/guide/built-in-functions.md is a build product and is gitignored — do not commit or hand-edit it. It is generated from two committed sources:

  • prose (intro, tips) lives in docs/guide/built-in-functions.tmpl.md, which holds the empty AUTOGENERATED:CATEGORIES and AUTOGENERATED:FUNCTIONS markers where the generated regions go;
  • the category list (the page's table of contents) and the function table are both rendered from HyperFormula's API (getAvailableFunctions/getFunctionDetails), i.e. from the catalogue in src/interpreter/functionMetadata/, in a single pass — so the list links to exactly the sections the page has.

npm run docs:generate-function-docs splices both regions into the template and writes the gitignored page; it runs automatically as the first step of npm run docs:build and npm run docs:dev. To change the wording, edit the template; to change a function's row, edit its catalogue metadata.

HyperFormula docs directory structure

docs                            # All documentation files
├── .vuepress                   # All VuePress files
│   ├── components              # Vue components
│   ├── dist                    # The docs output. Both the docs and the API reference are built into this folder.
│   ├── plugins                 # VuePress plugins, incl. md-companions (see below)
│   ├── public                  # Public assets
│   ├── styles                  # Style-related files
│   ├── subtheme                # Subtheme files
│   ├── templates               # HTML templates
│   ├── theme                   # Local theme extending the default theme (see below)
│   ├── config.js               # VuePress configuration
│   ├── enhanceApp.js           # VuePress app-level enhancements
│   └── highlight.js            # Code highlight configuration
├── api                         # The API reference files, generated automatically from JsDoc. Do not edit!
├── guide                       # The docs source files: Markdown content. built-in-functions.md is the one exception: a generated build product (see above)
├── api-ref-readme.md           # The API reference welcome page
├── index.md                    # The main docs portal welcome page
└── README.md                   # The file you're looking at right now!

Agent-friendly build outputs

npm run docs:build produces docs meant to be read by both people and AI coding agents:

  • HTML + Markdown per page — every guide page is built as both an .html page and a companion .md file with the same content, via the md-companions VuePress plugin (.vuepress/plugins/md-companions). The companion lives next to its HTML page, e.g. guide/basic-usage.html and guide/basic-usage.md.
  • llms-full.txt — all guide pages concatenated into one Markdown file at the docs root (/docs/llms-full.txt), so an agent can fetch the whole corpus in a single request instead of crawling page by page.
  • "View as Markdown" link — every guide page shows a small link near the top of its content that navigates to that page's .md companion (rendered via the local theme in .vuepress/theme, which overrides the default theme's Layout.vue).
  • "Set up your coding agent" page — guide/setup-coding-agent.md explains how to point Claude Code, Cursor, Copilot, and other agents at these machine-readable docs, and embeds the CodingAgentWizard component: an interactive picker that shows the right setup instructions for the agent you choose.