Hyperbook

Hyperbook is a quick and easy way to build interactive workbooks, that support modern standards and run superfast. It works by compiling markdown to static pages.

Hyperbook makes writing interactive workbooks super simple while providing a good feature set.

You do not need any coding experience. You only need to create and edit Markdown files.

Getting Started

You can start working on a Hyperbook in three different ways. Choose the one which suits your style best.

VS CodeCLIWeb IDE

Install VS Code or VS Codium
Install the Hyperbook Extension for VS Code or VS Codium
Download the hyperbook-anywhere starter
Unzip the file
Open the folder in VS Code
Run the Hyperbook: Show side preview command

You need to have Node version 16 or higher installed on your system.

Run npm create hyperbook and follow the wizard to create your first Hyperbook.
Run npx hyperbook dev to start the development server.
Visit https://localhost:8080 with your favorite web browser.
Modify or add new pages to your Hyperbook by using your favorite editor.

Most platforms for collaborative version control have an integrated Web IDE like GitLab or GitHub.

So you can just fork one of our starters and get going:

If you use this approach you will not be able to see a representative preview. In most cases only a normal Markdown preview, which lacks some features of Hyperbook.

Deploy

The main goal of writing a Hyperbook is to have an interactive workbook. For this you have to deploy the exported Hyperbook to a host.

Luckily GitHub Pages, GitLab Pages and Vercel are free to use options, which are already setup for you, if you used one of our starters, like hyperbook-anywhere.

You just have to push your files to GitHub or GitLab.

If you use the CLI version you can also export your Hyperbook to static HTML files, which can be uploaded anywhere. For this you need to run:

npx hyperbook build

Then you need to copy the files from .hyperbook/out to your desired location.

Asset downloads and offline builds

The CLI downloads the large assets for Blockflow, Online IDE, SQL IDE, Excalidraw, OpenSCAD, GeoGebra, Pyodide, and Typst when a build first uses them. These downloads are verified and cached across projects. The exported book includes local copies.

Before working offline, prefetch the assets needed by your project:

npx hyperbook assets fetch
npx hyperbook build --offline
npx hyperbook dev --offline

Use npx hyperbook assets fetch --all to download every optional bundle. Set HYPERBOOK_ASSET_CACHE to choose the cache directory, for example when restoring a cache in CI. The default is your operating system's user cache directory. --offline reports missing assets and skips the CLI update check; elements that use external services still need a connection to those services.

Do not forget to set a basePath in your hyperbook.json.

Update

VS CodeCLIWeb IDE

Updates should happen automatically.

Update to the latest release of Hyperbook CLI using the following command.

npm update hyperbook --global

No Integration. No updates.

Migrate

When a release changes the syntax of an element in a way old pages no longer understand, migrate converts your book to the current syntax. It is needed for v0.115.0, which changed the IDEs (PyIDE, Web IDE, p5, OpenSCAD and Typst) to the syntax with several files; the element pages describe what changed and what replaced it.

Run the command in the directory of your book:

npx hyperbook migrate

It rewrites the pages and the snippets they use and pins the id of every IDE it changes, so readers keep the code they saved. Only the parts that changed are replaced; the rest of the page stays as it is. What cannot be converted automatically is printed as a note for you to review.

The command refuses to run while your project has uncommitted changes. Commit them first, so you can review the migration with git diff and undo it with git checkout, or pass --force to run anyway. Use --dry-run to see what would change without writing anything:

npx hyperbook migrate --dry-run

Support

We are happy to hear from you, if you need custom support or features for your application.

You can also join our Matrix Channel or connect with us on Twitter.

Hyperbook is maintained by OpenPatch, an organization for educational assessments and training. If you need help or create a Hyperbook get in touch.