Put your docs online for basically nothing
A customer with a question needs an answer at a stable URL. You can provide that with a couple of Markdown files and a static host.
In this tutorial, you'll build a small Docusaurus site for Slot, a fictional booking API. It will have an introduction and a guide that makes a successful request to a local demo. Then you'll put the docs online.
You need Node.js 24, npm, a text editor, and a terminal. For the deployment, you also need Git and GitHub and Cloudflare accounts. Check your Node version with node --version.
1. Create the project
Create an empty folder and work inside it:
mkdir slot-docs
cd slot-docs
mkdir docs static
Create package.json:
{
"name": "slot-docs",
"version": "1.0.0",
"private": true,
"scripts": {
"start": "docusaurus start",
"build": "docusaurus build",
"serve": "docusaurus serve",
"demo-api": "node demo-api.mjs"
},
"engines": { "node": ">=24" },
"dependencies": {
"@docusaurus/core": "3.10.2",
"@docusaurus/preset-classic": "3.10.2",
"@mdx-js/react": "3.1.1",
"prism-react-renderer": "2.4.1",
"react": "18.3.1",
"react-dom": "18.3.1"
}
}
Install the dependencies:
npm install
Keep the generated package-lock.json. It records the dependency tree so a later deployment can use npm ci to install the same versions.
The official Docusaurus scaffold is another way to start. We're creating the files directly so there's no sample blog, homepage, or extra content to remove.
2. Configure a docs-only site
Create docusaurus.config.ts in the project root:
import type { Config } from '@docusaurus/types';
const config: Config = {
title: 'Slot docs',
url: 'https://slot-docs.example.com',
baseUrl: '/',
trailingSlash: true,
onBrokenLinks: 'throw',
markdown: { hooks: { onBrokenMarkdownLinks: 'throw' } },
presets: [
[
'classic',
{
docs: { routeBasePath: '/', sidebarPath: './sidebars.ts' },
blog: false,
},
],
],
themeConfig: {
navbar: { title: 'Slot docs' },
},
};
export default config;
routeBasePath: '/' puts the documentation at the root of the site. blog: false disables the blog. The two broken-link settings make a production build fail when your docs link to a missing local page.
url is a placeholder for now. Replace it with the public origin after you choose your deployment address. Keep baseUrl as / for a site served at the root of a domain. See the Docusaurus configuration reference for sites hosted under a subdirectory.
Create sidebars.ts:
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
guides: ['intro', 'find-a-booking'],
};
export default sidebars;
The sidebar uses document IDs, which come from filenames without their extensions.
3. Give the reader a first task
Create docs/intro.md:
---
title: Slot docs
slug: /
---
Slot is a fictional booking API. Use this local demo to learn how to read a booking and interpret its status.
Start with [Find a booking](./find-a-booking.md). You need Node.js 24 and a terminal; you don't need an account or a real API key.
The slug makes this page the homepage. Its first useful link leads to an action.
Download the demo server and save it as demo-api.mjs in the project root. It uses Node's built-in HTTP server and only listens on your computer. You can also find it in the finished example.
Create docs/find-a-booking.md with this content:
---
title: Find a booking
---
You'll retrieve one booking from the local demo API. You need Node.js 24, curl, and the example project.
## Start the demo
From the project folder, run:
```bash
npm run demo-api
```
Leave that terminal running. In a second terminal, request the example booking:
```bash
curl --fail-with-body \
http://127.0.0.1:4010/bookings/book_123 \
--header 'Authorization: Bearer demo-key'
```
You receive HTTP `200` with this JSON:
```json
{ "id": "book_123", "status": "confirmed" }
```
The booking is confirmed. The demo always returns this fixture; it doesn't make a real reservation.
## If the request fails
- Connection refused: start the demo server and leave its terminal open.
- HTTP `401`: send the exact Authorization header shown above.
- HTTP `404`: use `book_123`; the demo has no other bookings.
Stop the server with **Ctrl+C** when you're done.
For a real API, replace the fixture with a supported sandbox task. Explain how to get credentials before asking someone to use them. Give the expected result and the likely failures alongside the command.
4. Check the site and the task
Start the docs:
npm start
Open the local address printed in the terminal. Follow the guide in the browser, start the API in a second terminal, and run the curl command in a third. Check that the response matches the page.
Stop the docs development server, then check the production output:
npm run build
npm run serve
Open the address printed by serve. Load the homepage, follow Find a booking, and refresh that page directly. A development server succeeding doesn't establish that a production build works.
5. Put it in GitHub
Create .gitignore:
node_modules/
.docusaurus/
build/
.DS_Store
Create .node-version containing 24. Then initialize the repository:
git init -b main
git add package.json package-lock.json docusaurus.config.ts sidebars.ts docs demo-api.mjs .gitignore .node-version
git commit -m "Create Slot documentation"
Create an empty GitHub repository. Follow GitHub's instructions to add it as the origin remote and push main. Keep the lockfile in Git; leave dependencies and generated output out.
6. Deploy the static files
In Cloudflare's dashboard, create a Pages project connected to that GitHub repository. Choose main as the production branch. Use these settings:
| Setting | Value |
|---|---|
| Root directory | Repository root |
| Build command | npm run build |
| Build output directory | build |
| Environment variable | NODE_VERSION = 24 |
Cloudflare maintains a Docusaurus deployment guide if the dashboard labels have moved. This setup publishes static files; it doesn't need Pages Functions.
After the first deployment, copy its https://YOUR-PROJECT.pages.dev origin into url in docusaurus.config.ts. Commit and push that change. The next deployment uses the right public URL for canonical links and the sitemap.
Open the public homepage and /find-a-booking/ directly. Check them at a narrow browser width. Then edit one sentence, commit it, and push. Confirm that Pages publishes the edit. You've checked the whole path from source to customer.
The demo API stays on the reader's computer. Static hosting publishes the instructions, not a running Node server.
Cost and maintenance
You now have a docs site with no required paid docs service. The default hosting address avoids a domain purchase. Cloudflare documents free static asset requests; its free plan has build and file limits, including 500 builds per month and 20,000 files. Check the pricing and limits before deploying.
Someone still needs to keep the guide accurate and update dependencies. Start with those responsibilities assigned. You can add the bigger workflow once there's enough content and contribution to need it.