HPP Builders

House Party Protocol official documentation — built with Docusaurus and hosted on GitHub Pages at docs.hpp.io.

• Live site: https://docs.hpp.io (the hpp-io.github.io/docs URL redirects here)
• Migrated from: the previous GitBook site (hpp-io/hpp-docs)

Prerequisites

• Node.js >= 20 (CI uses 22)
• npm

Local development

npm install        # install dependencies (first time only)

npm start          # dev server with hot reload -> http://localhost:3000/
npm run build      # production build (validates links + generates search index)
npm run serve      # serve the production build -> http://localhost:3000/
npm run typecheck  # TypeScript type check
npm run clear      # clear the Docusaurus cache

Note

• Local search only works after npm run build && npm run serve. The search index is generated at build time, so it is not available under npm start.
• The production site is served at the docs.hpp.io custom domain (baseUrl: '/').

Content structure

Documentation lives in docs/. The sidebar is defined manually in sidebars.ts to preserve the original ordering. Pages that use tabs (Getting Started) are .mdx; all other pages are plain .md (markdown.format: 'detect').

Contributing

To add or update a documentation page:

1. Branch from main: git checkout -b docs/<topic>.
2. Add the page under the relevant docs/<section>/ folder (e.g. docs/community/my-page.md). Use .md for normal content; use .mdx only when the page needs tabs or other JSX.
3. Register it in sidebars.ts: add the page id — its path under docs/ without the extension (e.g. community/my-page) — to the right category. Ordering is manual, so position it where you want it to appear.
4. Link to other docs by their source path ([Token Address](../getting-started/hpp-contracts.mdx)), and put images in static/img/, referenced as /img/<file>.
5. Preview with npm start; run npm run build before pushing — the build fails on broken links (onBrokenLinks: 'throw'), so this catches mistakes early.
6. Open a pull request to main. CI builds and audits it; once merged, it auto-deploys to https://docs.hpp.io.

A minimal page looks like this:

---
title: My Page
description: One-line summary (used for SEO and search).
---

# My Page

Your content here.

For a tabbed page, name the file .mdx and use the theme's Tabs components:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="a" label="Tab A">Content A</TabItem>
  <TabItem value="b" label="Tab B">Content B</TabItem>
</Tabs>

Deployment

Pushing to main triggers .github/workflows/deploy.yml, which builds the site and deploys it to GitHub Pages. Pull requests are validated by .github/workflows/test.yml (build + security audit).

GitHub Pages must use GitHub Actions as its source (Settings → Pages → Build and deployment → Source). This can also be set via the API:

gh api repos/hpp-io/docs/pages -X POST -f build_type=workflow

Custom domain

The site is served at https://docs.hpp.io over HTTPS; hpp-io.github.io/docs redirects here.

• Pinned by static/CNAME (docs.hpp.io) and url / baseUrl: '/' in docusaurus.config.ts, and set as the GitHub Pages custom domain.
• DNS: a CNAME record points docs.hpp.io → hpp-io.github.io (Cloudflare, proxy off / DNS-only so GitHub can issue the TLS certificate).

Security

Transitive advisories from the Docusaurus toolchain are pinned to patched versions via npm overrides in package.json (including serialize-javascript, uuid, brace-expansion, mermaid, minimatch, nanoid, fast-uri, js-yaml, postcss, shell-quote, svgo, webpack-dev-server, body-parser, and dompurify). Most of these packages are build-time or local-dev only and are not present in the deployed static site.

CI fails on high/critical advisories (npx audit-ci --config audit-ci.jsonc). Advisories that have no upstream fix are allowlisted one by one in audit-ci.jsonc, each with the reasoning recorded next to it — the gate still fails on anything not listed there.

Currently allowlisted: the two image-size parser DoS advisories (CVE-2025-71330, CVE-2025-71329). image-size has had no release since 2025-04-02 and no patched version exists; Docusaurus tracks replacing it as a breaking change targeted at v4 (#12231), so it will not clear on the 3.x line. It is reached only through @docusaurus/mdx-loader when measuring images at build time, never in the deployed site.

Build and deploy jobs carry a timeout-minutes bound so that an infinite-loop advisory of this kind can cost at most one short job rather than a 6-hour runner hold.