doQumentation — Open-source website for IBM Quantum's tutorials and learning content

IBM Quantum's open-source content

IBM provides a wealth of quantum computing learning material — all open source under CC BY-SA 4.0:

• Learning — Structured courses from quantum basics to advanced topics
• Tutorials — 40+ tutorials on transpilation, error mitigation, and more
• Documentation — Guides and API reference for Qiskit
• Source repo — All content on GitHub

Their Quantum Platform is always up-to-date and well-designed — the best place for reading, learning, and reference.

What this project adds

IBM's Qiskit documentation is open source (CC BY-SA 4.0), but their web application is not. doQumentation adds an open-source frontend with live code execution, automatic credential injection, and simulator mode — independently hostable, runnable offline, and deployable on RasQberry.

See it live at doQumentation.org — browse tutorials, guides, and courses, execute code via Binder, no install required.

Content: 42 Tutorials, 171 Guides, 154 Course pages, 14 Modules (~380 pages total).

Deployment Tiers

	GitHub Pages	Docker (lite)	Docker (jupyter)	RasQberry
Browse tutorials, guides, & courses	Yes	Yes	Yes	Yes
Full-text search	Yes	Yes	Yes	Yes
Execute code	Via Binder	Via Binder	Local Jupyter	Local Jupyter
Open in JupyterLab	—	—	Planned	Yes
Offline access	—	Yes	Yes	Yes

Quick Start

View Online

doqumentation.org — browse tutorials and courses, execute code via Binder, no install required.

Run with Podman / Docker

# Full stack: site + Jupyter + Qiskit (~3 GB)
podman run -p 8080:80 -p 8888:8888 ghcr.io/janlahmann/doqumentation:jupyter

Access at http://localhost:8080. Using Docker instead? Just replace podman with docker — the commands are identical. Or build locally with podman compose --profile jupyter up. Images are multi-arch (linux/amd64 + linux/arm64).

Jupyter token: The full-stack container generates a random authentication token at startup (printed in the container logs). Code execution through the website on port 8080 is transparent — no token needed. Direct JupyterLab access on port 8888 requires the token. To set a fixed token: JUPYTER_TOKEN=mytoken podman run ...

Deploy to RasQberry

Note: RasQberry deployment is under development. Instructions will be provided soon.

Development

Prerequisites: Node.js 18+, Python 3.9+

git clone --recurse-submodules https://github.com/JanLahmann/doQumentation.git
cd doQumentation
npm install
python scripts/sync-content.py --sample-only  # or without flag for full sync
npm start

Other commands:

npm run build          # Production build
npm run build:search   # Build search index
npm run typecheck      # Type check
npm run sync-content   # Sync content from upstream

How It Works

Tutorial content is sourced from Qiskit/documentation and transformed into a Docusaurus site with executable code blocks. Python code connects to a Jupyter kernel via thebelab:

• GitHub Pages: Uses Binder for remote execution (first run may take 1-2 min)
• Docker / RasQberry: Connects to a local Jupyter server with Qiskit pre-installed
• Custom: Configure any Jupyter endpoint in Settings

On RasQberry, an Open in Lab button opens the full notebook in JupyterLab.

Content Synchronization

python scripts/sync-content.py                              # Full sync (requires git, Python, jupyter)
python scripts/sync-content.py --sample-only                # Sample only (for testing)
python scripts/sync-content.py --no-clone                   # Use existing upstream clone
python scripts/sync-content.py --freshness-report report.md # Markdown report of EN-vs-upstream
                                                            # drift + per-locale staleness

Rolling back a bad sync. If a content sync introduces a regression, revert the merge commit on main and force-push (or use the GitHub "Revert" button). The deploy.yml workflow republishes the prior site within ~5 min. Translated locales follow on the next deploy-locales.yml run. The upstream-docs/ submodule pointer is part of the revert, so subsequent sync-content.py runs replay against the rolled-back upstream until the underlying issue is fixed.

Project Structure

doQumentation/
├── upstream-docs/                 # Git submodule → Qiskit/documentation (CC BY-SA 4.0)
├── docs/                          # Tutorial content (MDX, mostly generated)
│   └── index.mdx                  # Homepage (source of truth, preserved by sync)
├── notebooks/                     # Original .ipynb for JupyterLab (generated)
├── src/
│   ├── components/
│   │   ├── ExecutableCode/        # Run/Stop toggle, thebelab, kernel injection
│   │   ├── CourseComponents/      # IBMVideo, DefinitionTooltip, Figure, etc.
│   │   ├── GuideComponents/       # Card, CardGroup, OperatingSystemTabs, etc.
│   │   └── OpenInLabBanner/       # "Open in JupyterLab" button
│   ├── config/
│   │   └── jupyter.ts             # Environment detection, credential/simulator storage
│   ├── css/
│   │   └── custom.css             # Carbon-inspired styling
│   ├── pages/
│   │   └── jupyter-settings.tsx   # Settings (IBM credentials, simulator, custom server)
│   └── theme/
│       ├── CodeBlock/             # Swizzle: wraps Python blocks with ExecutableCode
│       └── MDXComponents.tsx      # IBM component stubs (Admonition, Image, etc.)
├── scripts/
│   ├── sync-content.py            # Pull & transform content from upstream
│   ├── sync-deps.py               # Sync Jupyter deps with arch exception rules
│   └── setup-pi.sh                # Raspberry Pi setup
├── binder/
│   ├── jupyter-requirements.txt       # Full Qiskit deps (cross-platform)
│   └── jupyter-requirements-amd64.txt # amd64-only extras
├── .github/workflows/
│   ├── deploy.yml                 # Sync → build → deploy to GitHub Pages
│   ├── docker.yml                 # Multi-arch Docker → ghcr.io
│   └── sync-deps.yml              # Weekly Jupyter dependency sync auto-PR
├── Dockerfile.jupyter             # Full stack: site + Jupyter + Qiskit (~3 GB; also serves static site)
├── docker-compose.yml             # jupyter service (jupyter-local target)
├── nginx.conf                     # SPA routing + Jupyter proxy
├── docusaurus.config.ts           # Site configuration
└── sidebars.ts                    # Navigation (imports generated sidebar JSONs)

Deployment

Pushing to main automatically deploys to GitHub Pages and builds two multi-arch Docker images (linux/amd64 + linux/arm64) to GitHub Container Registry.

Contributing

The translations into 17 languages are machine-produced and then reviewed against the English source, page by page. That review is where help is most useful, and it is designed to be run by Claude Code rather than by hand.

• CONTRIBUTING-NOW.md — what we need right now: which locales still have unreviewed pages, how much is left in each, and what recent rounds have been finding. Regenerated daily; start here.
• CONTRIBUTING-REVIEWS.md — the complete recipe for running one review round.
• CONTRIBUTING-TRANSLATIONS.md — for translating newly-synced English content.

The shortest path: fork the repo, clone your fork, open Claude Code in it and say "I want to help with reviews. What should I do?" The repo's CLAUDE.md routes that to the recipe, checks your setup and asks for what is missing. You need a Claude Max subscription, git, python3, the gh CLI, and po4a + gettext + polib to render a locale locally.

Claim a locale first so two people don't review the same one: open an issue with the Claim a locale template (label translation-claim); the open claims are listed in CONTRIBUTING-NOW.md.

Sync your fork with upstream main before every session — not just on the first clone. Which pages still need work is read from a status file that every merged round rewrites, so a fork that is a few days old will send you to re-do pages someone has already finished:

gh repo sync <YOUR-USER>/doQumentation --source JanLahmann/doQumentation --branch main

License

This repository is dual-licensed:

• Code (scripts, source files, configuration) — Apache License 2.0
• Content (tutorials, guides, courses, media, translations) — CC BY-SA 4.0

Upstream content from Qiskit/documentation © IBM Corp is tracked as a git submodule in upstream-docs/. Translations in i18n/ are adapted material under CC BY-SA 4.0. See NOTICE for full attribution.

Acknowledgments

• IBM Quantum for Qiskit and the open-source tutorials
• Docusaurus for the documentation framework
• thebelab for Jupyter integration

---

Qiskit documentation content © IBM Corp. Code is licensed under Apache 2.0; content (tutorials, courses, media, translations) under CC BY-SA 4.0. See NOTICE for full attribution. IBM, IBM Quantum, and Qiskit are trademarks of IBM Corporation. doQumentation is part of the RasQberry project and is not affiliated with, endorsed by, or sponsored by IBM Corporation.

Part of the Fun with Quantum family

This project is part of Fun with Quantum, a family of open-source quantum outreach projects: Fun with Quantum · RasQberry Two · RasQberry One · Quantego · Qutie · Qoffee-Maker · Entangible · CertiQ · QuBins · QAMPoser.

God does play dice. Come play, build, learn.