HogwartsMP documentation

Public, maintainer-authored guides for the HogwartsMP scripting API.

The closed-source Mod remains authoritative for generated client and server API contracts. It publishes those contracts as immutable artifacts to MafiaHub Services. This repository downloads a public contract revision, composes it with the authored guides, generates the complete site, and deploys it to the standalone documentation service.

Structure

• guides/ contains scripting concepts and tutorials. Each subdirectory is a sidebar section named after the directory (guides/Getting started/first-resource.md is served at /guides/getting-started/first-resource/). Sections are ordered by the lowest sidebar.order among their pages, so each section owns a range: Getting started 100–199, Core concepts 200–299, Players 300–399, NPCs and creatures 400–429, PvE 430–449, Encounters 450–469, PvP 470–499, World 500–549, Room of Requirement 550–599, User interface 600–699, Camera and sound 700–799, Mounts and races 800–849, Quidditch 850–899, Hosting a server 900–999. A section added between two takes the free part of a hundred, such as 450–499.
• Image directories live beside the Markdown document that references them.
• docs.config.json owns the generator pin, branding, links, navigation, and community-content mapping.
• scripts/sync_contract.mjs downloads and verifies the public scripting contract.
• scripts/public_contract.mjs drops underscore-prefixed declarations, the Mod's internal QA and diagnostic hooks, from a copy of the contract so the site documents only the public API.
• scripts/docs.mjs is the single local and CI generation entrypoint.
• scripts/check_samples.mjs type-checks every JavaScript and TypeScript sample in guides/ against the public contract.
• scripts/check_links.mjs checks that every link and anchor on the built landing and guide pages resolves.
• src/styles/production.css is shared by the standalone site and local preview.

The closed-source Mod repository owns only contract generation and publication. It does not render, deploy, or trigger this documentation website.

Contributing

Open a pull request with the guide or asset change. Keep local image references relative to the Markdown file and avoid active HTML such as scripts, forms, iframes, or inline event handlers.

Local preview

The preview is completely public and does not require the closed-source Mod, Hogwarts Legacy, a Services checkout, platform credentials, or an upload token. It downloads the same unauthenticated scripting contract used by CI and runs the complete production generator, including Server API, Client API, guides, branding, and navigation.

Install Node.js 22 or newer, clone this repository, and install the pinned dependencies:

git clone https://github.com/hogwarts-mp/docs.git
cd docs
corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile

Start the local development server:

pnpm dev

Open http://localhost:4321/. The first run downloads the current testing contract into the ignored .cache/ directory. Edit Markdown, colocated images, docs.config.json, or src/styles/production.css; the complete production site rebuilds and the browser refreshes automatically.

To download the contract without starting the preview:

pnpm docs:sync

Set HOGMP_CONTRACT_CHANNEL, HOGMP_CONTRACT_REVISION, or HOGMP_API_URL to select another public contract. A manual deployment can pin an exact immutable revision; otherwise it resolves the selected public channel when the workflow starts.

Before opening a pull request, verify the affected pages at desktop and mobile widths and run:

pnpm build
pnpm docs:links
pnpm docs:check
git diff --check

pnpm docs:check compiles each js and ts fence against the contract's TypeScript declarations, so a sample that calls a removed or renamed API fails CI. Start a sample with a comment naming its environment, such as // server or // src/client/main.ts, to check it against that environment alone; any other sample passes when it type-checks against at least one. Undeclared lowercase names and relative imports are assumed to be the reader's own code and are not reported. A js sample may read an unknown event payload freely; a ts sample has to narrow it, as its reader would.

The generated dist/ is the same static artifact deployed in CI. Merges to main deploy against the selected contract channel, while the Mod independently publishes contracts and stops there.