IntroToQuantumComputing

IntroToQuantumComputing — an example MarkdownToNotebook book

A worked example of authoring a Wolfram Book Tools book from markdown. The two chapters are modelled on the first two lessons of the Wolfram Quantum Framework course (QuantumFramework/OngoingProjects/Courses/IntroToQuantumComputing/), augmented with the book-style back matter the original notebooks did not have: exercises, solutions, vocabulary, Q&A, tech notes, references, and a summary.

Layout

• chapters/ — one markdown file per chapter
  • 01-what-is-quantum-computation.md
  • 02-building-blocks-of-quantum-circuits.md
• build.wls — converts each *.md to a book/<n>-<slug>.nb
• book/ — output chapter notebooks (gitignored; generated by build.wls)

Build

wolframscript -f build.wls            # local build into ./book/
wolframscript -f build.wls --publish  # also CloudDeploy each notebook (public)

The first build evaluates every ```wl cell and caches its output (PersistentObjects keyed by cumulative content hash). Subsequent builds only re-evaluate the cells whose code (or any preceding cell) has changed.

After the chapters are built, the build script:

1. Stamps ExpressionUUIDs on every heading cell (FE round-trip) so the TOC buttons have stable jump targets.
2. Writes book/Contents.nb using the same inline TOCTitle / TOCSection / TOCSubsection / TOCSubsubsection stylesheet the WolframBookTools paclet's WBTMakeContentsFromDialog writes — the TOC visually matches what the palette's "Make Contents" button produces. The cell shape mirrors WolframBookToolsPrivatemakeContentsCellsToWrite (it can't be called directly because it uses Get on the chapter .nb, which trips on M2N's serialized SummaryBox output).
3. Writes book/Master.nb: concatenates every chapter's cells under a single BookToolsStyles.nb stylesheet (mirroring the Master.nb step of WBTCreateCorrespondingPrintDirectory), with any Tentative / WebOnly / Suggestion editorial markers stripped.

Published (Wolfram Cloud)

• Master.nb — single concatenated book
• Contents.nb — clickable TOC across chapters
• Chapter 1: What Is Quantum Computation?
• Chapter 2: Building Blocks of Quantum Circuits

Authoring with the Wolfram Book Tools palette

1. Install the palette: PacletInstall["WolframBookTools"] (or use https://www.wolfram-media.com/resources/).
2. After running build.wls, point File ▸ Palettes ▸ Book Tools ▸ Set Chapters Directory at the book/ directory. You can now use:
   • Open Chapter to load a chapter notebook
   • Make Contents to produce a Contents.nb with TOCSection / TOCSubsection / TOCSubsubsection cells across all chapters
   • Preview PDF to print a single chapter to PDF
   • Production Tools for typography, page breaks, line spacing, etc.

Re-authoring should happen in the markdown source, not in the notebooks — re-running build.wls would overwrite any in-notebook edits.

The Book Tools features that are exercised

Cell style / construct	Authored as
Section (chapter heading with CounterBox + SectionBar + CounterAssignments)	# Title + frontmatter ChapterNumber: N
Subsection / Subsubsection / Subsubsubsection	## / ### / ####
Text / CodeText / Item / ItemNumbered	prose / colon-suffix prose before code / - / 1.
Input / Output (evaluated, cached)	```wl fence
DisplayFormula	$$ math $$
SolvedExample + SolvedExampleNote + SolvedExampleInput + SolvedExampleOutput + SolvedExampleEndCap	::: solved-example fenced div
Theorem + TheoremStatement + Proof + ProofContent + ProofTheoremEndCap	::: theorem / ::: proof divs
Exercise + ExerciseInput + ExerciseOutput + ExerciseSolution + SolutionAnswer	## Exercises with ::: exercise + ::: solution divs
VocabularySection + VocabularyTable + VocabularyText	## Vocabulary with a 2-column pipe table
QASection + Question + Answer	## Q&A with Q. / A. paragraph lead-ins
TechNoteSection + TechNote + TechNoteInput + TechNoteOutput	## Tech Notes (paragraphs + ```wl blocks)
MoreExploreSection + MoreExplore + MoreExploreShortURL	## More to Explore (bullets + bare-URL lines)
SummarySection + SummaryNote + SummaryList	## Summary (paragraphs + bullets)
ReferenceSection + Reference	## References (bullets / paragraphs)

See docs/book-palette.md for the full button catalog and cell-style mapping.