# Docusaurus hosting

Host a Docusaurus documentation site: npm run build writes build/, and npx lobsite deploys it with a preview URL per deploy so docs changes get reviewed.

On the web at https://lobsite.com/hosting/docusaurus

```sh
npm run build && npx lobsite
```

Docusaurus builds into build/, and npx lobsite finds it and deploys it.

Docusaurus builds your documentation into a static site in `build/`: every doc and blog post as HTML, with search and navigation that run in the browser. Lobsite hosts that folder. Run `npm run build`, then `npx lobsite`, and your docs are live at a `*.lobsite.app` address with HTTPS. Every deploy also gets its own URL, which is handy for reviewing docs changes before they go live.

## How it works

1. **Build the docs** with `npm run build`. Docusaurus writes the site to `build/`, and fails the build on broken links by default.
2. **Run `npx lobsite`** in the project. It deploys `build/`, not `static/`. The first deploy needs no account and lasts 6 hours.
3. **Keep it** with the claim link, in a free account. After that, `npm run build && npx lobsite` updates the same address.

## url, baseUrl and trailing slashes

```js
// docusaurus.config.js
export default {
  url: "https://my-docs.lobsite.app",
  baseUrl: "/",
};
```

- **`url`** is your site's address. Docusaurus uses it for canonical links and the sitemap.
- **`baseUrl`** is `/` on Lobsite. A GitHub Pages project site uses `/repo-name/`; leaving that in breaks every asset link.
- **`trailingSlash`** can be left out. Docs built as `docs/intro/index.html` open at `/docs/intro/`; `/docs/intro` redirects there.

## Reviewing docs changes

Docs are written by many people and often reviewed by someone else. `lobsite deploy --preview` publishes the build at its own URL without touching the live docs, so a reviewer reads the change as it will look. `lobsite promote` makes it live, and `lobsite rollback` goes back to the previous version in one step. Moving pages around? Add redirects for the old paths to `lobsite.toml` so links from search results and other sites keep working; the [Redirect Generator](https://lobsite.com/tools/redirect-generator) writes the rules. AI coding agents can run the same deploy with `npx -y lobsite --yes`, which never stops to ask a question.

## Docusaurus hosts compared

| | Lobsite | GitHub Pages | Netlify | Vercel |
|---|---|---|---|---|
| Builds the docs for you | No: you deploy `build/` | In GitHub Actions, or `docusaurus deploy` | Yes | Yes |
| Preview URL for every deploy | Yes | No | Yes | Yes |
| Rollback in one step | Yes | Revert a commit | Yes | Yes |
| Account before the first deploy | No: live 6 hours, then keep it free | Yes, and a repository | Yes | Yes |
| Custom domain | Yes, free | Yes, free | Yes | Yes |

GitHub Pages works well for open-source docs that live next to the code. Lobsite suits docs you build locally or in CI and want to preview, promote and roll back without a Git workflow around the hosting.

## Frequently asked questions

### Which baseUrl should Docusaurus use on Lobsite?

`/`. The site is served from the top of its address. Only a GitHub Pages project site needs `/repo-name/`.

### Does Docusaurus search work on a static host?

Yes. Algolia DocSearch runs in the visitor's browser, and local search plugins build their index into `build/`. Neither needs a server.

### Can I host versioned Docusaurus docs?

Yes. Every version is built into `build/` as its own pages, so they all deploy together. Only the files that changed since the last deploy are uploaded.

### How big can a Docusaurus site be?

On the free plan, up to 1,000 files and 50 MB per deploy, which fits most docs sites. Larger docs with many versions or images need the paid plan, coming soon; every limit is on the [limits](https://lobsite.com/docs#limits) table.