The Snap! Reference Manual

Read online at docs.snap.berkeley.edu · Download the PDF

The latest production build of the manual is published from main to GitHub Pages on every push:

Format	URL
HTML site	https://docs.snap.berkeley.edu/
Full manual (PDF)	https://docs.snap.berkeley.edu/snap-manual.pdf
Manual without block reference (PDF)	https://docs.snap.berkeley.edu/snap-manual-no-blocks-ref.pdf
Block reference only (PDF)	https://docs.snap.berkeley.edu/snap-blocks-ref.pdf
Original Snap! 8 PDF (legacy reference)	https://snap.berkeley.edu/snap/help/SnapManual.pdf

For PRs, an unmerged-but-built copy of the PDFs is attached to each CI run as a GitHub Actions artifact (kept for 10 days). See "Previewing the PDFs for a PR" below.

The reference manual for the Snap! programming language. (GitHub)

Note

The web manual is a "translation" of the original PDF, which was last largely updated for Snap! 8. We're first working on making the web version readable, then we'll update the content to match recent Snap! releases.

Citing Snap! and the Snap! Manual

To cite the manual specifically:

DOI: https://doi.org/10.5281/zenodo.16892852

Harvey, B., & Mönig, J. (2022). Snap! Reference Manual. Zenodo. https://doi.org/10.5281/zenodo.16892852

@book{harvey_2022_16892853,
  author       = {Harvey, Brian and
                  Mönig, Jens},
  title        = {Snap! Reference Manual},
  publisher    = {Zenodo},
  year         = 2022,
  month        = aug,
  doi          = {10.5281/zenodo.16892852},
  url          = {https://doi.org/10.5281/zenodo.16892852},
}

To cite Snap! in general, please use the following citation:

DOI: https://doi.org/10.5281/zenodo.15460068

Mönig, J., & Harvey, B. (2025). Snap! (latest). Zenodo. https://doi.org/10.5281/zenodo.15460068

@software{monig_2025_15460069,
  author       = {Mönig, Jens and
                  Harvey, Brian},
  title        = {Snap!},
  month        = may,
  year         = 2025,
  publisher    = {Zenodo},
  version      = {latest},
  doi          = {10.5281/zenodo.15460068},
  url          = {https://doi.org/10.5281/zenodo.15460068},
}

These DOI's always point to the latest version of the manual and Snap! software, respectively. You can visit Zenodo to cite a specific version if you need to.

Authors

Brian Harvey, Jens Mönig, Michael Ball, Jadge Hügle, Victoria Phelps, Mary Fries

Jupyter Book 2 (MyST)

This version of the Snap! manual is built using Jupyter Book 2 via MyST Markdown.

Installation

You need Node.js (v18+) to install MyST:

npm install -g mystmd

macOS (via Homebrew):

brew install node
npm install -g mystmd

It is also recommended to install the MyST VSCode extension.

Building the book

While writing content (live preview):

npm run dev
# OR
jupyter-book start

This builds the web version and opens it in the browser. The page reloads automatically as you save changes.

To build the final HTML:

jupyter-book build --html

Output is placed in _build/html/.

To build the PDFs (requires a TeX Live install):

jupyter-book build --pdf

This produces three PDFs in output/:

• snap-manual.pdf — the full manual.
• snap-manual-no-blocks-ref.pdf — the manual without the per-block reference section.
• snap-blocks-ref.pdf — only the per-block reference.

See docs/latex.md for details on the PDF pipeline and the local LaTeX template at _latex-template/. The two filtered variants are configured by articles: lists in myst.yml, generated from toc.yml by _support/scripts/generate-pdf-exports.py — rerun that script after editing the toc.

Writing Style

Please read docs/STYLEGUIDE.md. Other developer docs live in docs/.

VSCode and Editing

Install the MyST VSCode extension for syntax highlighting and live preview.

Document Conversion

If you are making large updates to the md structure, it may be worth working on the script to convert the Word document to markdown. The script assumes you have pandoc installed and available in your path.

cd _support/conversion
ruby convert-word-doc.rb

Published Book

The website is hosted on GitHub Pages at docs.snap.berkeley.edu. On every push to main, the myst.yml workflow builds the HTML site and three PDFs (snap-manual.pdf, snap-manual-no-blocks-ref.pdf, snap-blocks-ref.pdf), then publishes them together to the gh-pages branch. All three PDFs are therefore available at the URLs in the table at the top of this README.

Previewing the PDFs for a PR

The same workflow also runs on pull requests. It does not publish to gh-pages, but it does attach the freshly built PDFs to the workflow run as a GitHub Actions artifact named snap-manual-pdfs with a 10-day retention. The artifact contains all three PDFs.

To grab the PR's PDFs:

1. Open the PR on GitHub and click Checks → Deploy MyST / Jupyter Book to GitHub Pages.
2. On the run page, scroll to the Artifacts section at the bottom.
3. Download snap-manual-pdfs — it expands to a zip with all three PDFs.

Or from the CLI:

gh run download --name snap-manual-pdfs --repo snap-cloud/manual

License

AGPL, CC-BY-NC-SA