{"version":"1","records":[{"hierarchy":{"lvl1":"Introduction"},"type":"lvl1","url":"/intro","position":0},{"hierarchy":{"lvl1":"Introduction"},"content":"Updated: 31 Oct 2025\n\nThis is the Jupyter Book 2 Workshop Template, designed to quickly and easily produce your own online interactive textbook as well as a high quality PDF enabled with Typst using \n\nJupyter Book 2 technology.\n\nThis template:\n\nprovides a ready-to-use Jupyter Book 2 structure for creating an online book (i.e., website),\n\nincludes a number of lessons to get started understanding key components of a book and how to edit it,\n\nincludes a GitHub Action workflow to automatically build and deploy your book online,\n\nprovides instructions for generating a high quality PDF with Typst using a ready-to-go template, then deploy it online automatically using GitHub Actions.\n\nHence, the template allows you to engage with JB2 (and the underlying software MyST) without installing any software on your own computer. You only need a web browser and a GitHub account (we provide details on how to work locally on your own computer). For those who are comfortable installing software locally (i.e., with a CLI) and/or do not want to use the template book structure, use the \n\nAdvanced Start instructions, denoted with red hot 🌶.\n\nAs this document serves both as a template and a guide, it has the following structure:\n\nA quick introduction to key Jupyter Book 2, MyST and Markdown concepts.\n\nA tutorial with several steps to introduce you to editing and building your own book.\n\nAdditional resources, for example, \n\nAdvanced Start instructions and \n\nSoftware.\n\nNote\n\nThe template and its content are not meant as a replacement of the documentation already available on the \n\nJupyter Book 2 website and the \n\nMyST website. It is designed to support new users of Jupyter Book 2 and MystMD, in particular for use in workshop settings where participants may not have time or ability to install the required software on a personal computer.","type":"content","url":"/intro","position":1},{"hierarchy":{"lvl1":"Markdown Cheat Sheet"},"type":"lvl1","url":"/cheat-sheet","position":0},{"hierarchy":{"lvl1":"Markdown Cheat Sheet"},"content":"Updated: 03 Nov 2025\n\nBelow is a set of frequently used markdown commands for Jupyter Book 2 made with MyST. A good practice is to download the source file by clicking the download icon at the top right of this page and inspect the code.","type":"content","url":"/cheat-sheet","position":1},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Book structure"},"type":"lvl2","url":"/cheat-sheet#book-structure","position":2},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Book structure"},"content":"We can distinguish between two structures: that of the book’s content (a collection of different documents), and the (internal) structure of the chapters which consists of content structured in sections and subsections.","type":"content","url":"/cheat-sheet#book-structure","position":3},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Table of Contents","lvl2":"Book structure"},"type":"lvl3","url":"/cheat-sheet#table-of-contents","position":4},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Table of Contents","lvl2":"Book structure"},"content":"In the myst.yml file, you can specify the structure of the book as shown in \n\nProgram 1.\nHere you can indicate which files belong to the book and in what order.\nYou can also create dropdown menus in your ToC by including children.\nWhen not specifying a ToC, all files are automatically included in alphabetical order.\n\n    - file: index.md                      # the landing page\n    - file: content/1_intro.md\n    - file: content/2_cheat_sheet.md\n    - file: content/lessons/your_turn.md          # dropdown menu\n      children:\n        - file: content/lessons/0_setup.md\n        - file: content/lessons/1_firstedit.md\n        - file: content/lessons/1_landingpage.md\n        - file: content/lessons/2_nextstep.md\n          children:\n            - file: content/lessons/2a_plugins.md\n        - file: content/lessons/reuse.md\n        - file: content/lessons/executable.md\n        - file: content/lessons/5_workflows.md\n        - file: content/lessons/6_pdfoverview.md\n          children:\n            - file: content/lessons/6a_myst.md\n            - file: content/lessons/6b_pdfgeneration.md\n            - file: content/lessons/6c_pdfoutput.md\n            # - file: content/lessons/6d_typsttemplate.md\n        # - file: content/lessons/7_styling.md\n        - file: content/lessons/8_init.md\n\n    - file: content/advanced_start.md\n    - file: content/software.md\n    - file: content/gallery.md\n\nProgram 1:The Table of Contents (ToC) for this book.\n\nIf you have specified a ToC and create a new file, you’ll need to add it to the myst.yml file to include it in the book.\nNote that this is a .yml file rather than a .md file.","type":"content","url":"/cheat-sheet#table-of-contents","position":5},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Headings","lvl2":"Book structure"},"type":"lvl3","url":"/cheat-sheet#headings-cheat-sheet","position":6},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Headings","lvl2":"Book structure"},"content":"To make sections within a page, use a number of # symbols at the beginning of a line.\nThe more #s increases the level of the heading.# Heading level 1\n## Heading level 2\n### Heading level 3\n\nTypically, a page only has a single level 1 heading, the page’s title and higher level headings are used for sections and subsections.\n\nTip\n\nDo not number your chapters and sections! This happens automatically.\n\nNote also that a structured sections are preferred, that is not skipping a heading.\n\nA chapter outline based on the headings in the page and their hierarchy is created automatically and shown in the right sidebar.","type":"content","url":"/cheat-sheet#headings-cheat-sheet","position":7},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Basic Formatting"},"type":"lvl2","url":"/cheat-sheet#basic-formatting","position":8},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Basic Formatting"},"content":"Markdown is a markup language where text formatting is done with small pieces of code (just like HTML). This is a table with some frequently used formatting options.\n\nTable 1:Some basic Markdown text formatting\n\nElement\n\nSyntax\n\nExample\n\nBold\n\n**bold text**\n\nBold\n\nItalic\n\n*italics*\n\nItalics\n\nEmphasis\n\n***emphasis***\n\nemphasis\n\nInline Formula\n\n$F = m \\cdot a$\n\nF = m \\cdot a\n\nFootnote\n\n - A footnote reference[^myref]  [^myref]: This is an auto-numbered footnote definition.\n\n- A footnote reference\n\nYou can create a new line by either a hard enter and a blank line, a \\ at the end of the line and enter, or two spaces at the end of the line.","type":"content","url":"/cheat-sheet#basic-formatting","position":9},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"New Lines","lvl2":"Basic Formatting"},"type":"lvl3","url":"/cheat-sheet#line-breaks","position":10},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"New Lines","lvl2":"Basic Formatting"},"content":"Generally, in markdown, a single hard enter does not create a new line. You need to use one of the options below.\n\nA new line with double space.\nA new line with a \\.A new line with a hard enter and blank line.\n\nNo new line with just a hard enter and text on the next line.\nLike this\n\nMarkdown syntaxA new line with double space.\nA new line with a `\\`.\\\nA new line with a hard enter and blank line.\n\nNo new line with just a hard enter and text on the next line.\nLike this","type":"content","url":"/cheat-sheet#line-breaks","position":11},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Mathematics and equations"},"type":"lvl2","url":"/cheat-sheet#mathematics-and-equations","position":12},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Mathematics and equations"},"content":"For STEM subjects, mathematical equations and symbol are essential.\nYou can include equations in JupyterBooks using the LaTeX syntax for mathematics.\n\nLabelled equations using double dollars, such as \n\n(1), can be referenced.\n\nF_{\\mathrm{res}} = m \\cdot a\n\nMarkdown syntax$$ F_{\\mathrm{res}} = m \\cdot a$$ (eq_newton)\n\nBut you can also write inline equations with single dollars.\n\ns=v_{\\mathrm{avg}}t\n\nMarkdown syntax$s=v_{\\mathrm{avg}}t$\n\nTable 2:Some examples of LaTeX mathematics notation\n\nName\n\nSyntax\n\nOutput\n\nGreek script\n\n\\Delta \\lambda\n\n\\Delta \\lambda\n\nroot\n\n\\sqrt{4}\n\n\\sqrt{4}\n\nsuperscript/power\n\nx^{2a}\n\nx^{2a}\n\nfraction\n\n\\frac{2}{3}\n\n\\frac{2}{3}\n\nsubscript\n\nx_{\\mathrm{avg}}\n\nx_{\\mathrm{avg}}\n\nmultiply\n\na \\cdot b\n\na \\cdot b\n\nderivative\n\n\\frac{\\Delta f}{\\Delta t}\n\n\\frac{\\Delta f}{\\Delta t}\n\nintegral\n\n\\int_a^b f(x) \\mathrm{d}x\n\n\\int_a^b f(x) \\mathrm{d}x\n\nsine\n\n\\sin(x)\n\n\\sin(x)\n\nYou can read about more of the LaTeX mathematics syntax in \n\nthe LaTeX wikibook\n\nTypst\n\nTypst equations are also supported in Jupyter Book. See \n\nTypst in Jupyter Book for more information.","type":"content","url":"/cheat-sheet#mathematics-and-equations","position":13},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Lists"},"type":"lvl2","url":"/cheat-sheet#lists","position":14},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Lists"},"content":"","type":"content","url":"/cheat-sheet#lists","position":15},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Ordered lists","lvl2":"Lists"},"type":"lvl3","url":"/cheat-sheet#ordered-lists","position":16},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Ordered lists","lvl2":"Lists"},"content":"Ordered lists can be made with automatically numbered items.\n\nitem 1\n\nitem 2.\n\nitem 3.\n\nMarkdown syntax1. item 1\n1. item 2.\n1. item 3.\n\nOr you can manually number the items\n\nitem 1\n\nitem 2.\n\nitem 3.\n\nMarkdown syntax1. item 1\n2. item 2.\n3. item 3.","type":"content","url":"/cheat-sheet#ordered-lists","position":17},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Unordered lists","lvl2":"Lists"},"type":"lvl3","url":"/cheat-sheet#unordered-lists","position":18},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Unordered lists","lvl2":"Lists"},"content":"Unordered lists use - or * for each item.\n\na\n\nb\n\nc\n\nMarkdown syntax- a\n- b\n- c","type":"content","url":"/cheat-sheet#unordered-lists","position":19},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Checklists","lvl2":"Lists"},"type":"lvl3","url":"/cheat-sheet#checklists","position":20},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Checklists","lvl2":"Lists"},"content":"You can also create checklists.\nThe checks are interactive, you can tick or untick them.\n\nCreate a markdown cheat sheet\n\nPublish online\n\nLet others test\n\nMarkdown syntax- [x] Create a markdown cheat sheet\n- [x] Publish online\n- [ ] Let others test\n\nReport issues\n\nJupyter Book 2 trusts on an active open source community. If you find any issues in your project, you can report them back to the \n\nJupyter Book GitHub repository, like this issue on the checklist not rendering properly: \n\n#2290.\n\nWhen reported, the developers will try to fix the issue as soon as possible - as can be seen above!","type":"content","url":"/cheat-sheet#checklists","position":21},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Tables"},"type":"lvl2","url":"/cheat-sheet#tables","position":22},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Tables"},"content":"In Markdown, tables are created with the separator |\n\nHeader 1\n\nHeader 2\n\nHeader 3\n\ntext 1\n\ntext 2\n\ntext 3\n\ntext 4\n\ntext 5\n\ntext 6\n\nMarkdown syntax|Header 1|Header 2|Header 3|\n|---|---|---|\n|text 1|text 2|text 3|\n|text 4|text 5|text 6|\n\nUsing a table directive, like \n\nTable 3 lets you add a caption and label so you can \n\nreference it.\n\nTable 3:An example table\n\nHeader 1\n\nHeader 2\n\nHeader 3\n\ntext 1\n\ntext 2\n\ntext 3\n\ntext 4\n\ntext 5\n\ntext 6\n\nMarkdown syntax:::{table} An example table\n:name: tl_example\n| Header 1 | Header 2 | Header 3 |\n|----------|----------|----------|\n| text 1   | text 2   | text 3   |\n| text 4   | text 5   | text 6   |\n:::","type":"content","url":"/cheat-sheet#tables","position":23},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Blocks"},"type":"lvl2","url":"/cheat-sheet#blocks","position":24},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Blocks"},"content":"","type":"content","url":"/cheat-sheet#blocks","position":25},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Tabs","lvl2":"Blocks"},"type":"lvl3","url":"/cheat-sheet#tabs","position":26},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Tabs","lvl2":"Blocks"},"content":"Text in tab 1\n\nText in tab 2\n\nMarkdown syntax::::{tab-set}\n:::{tab-item} Tab 1\nText in tab 1\n:::\n\n:::{tab-item} Tab 2\nText in tab 2\n:::\n::::","type":"content","url":"/cheat-sheet#tabs","position":27},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Cards","lvl2":"Blocks"},"type":"lvl3","url":"/cheat-sheet#cards","position":28},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Cards","lvl2":"Blocks"},"content":"header\n\nTitle\n\nWith some text\n\nfooter\n\nMarkdown syntax\n```{card} Title\n:header: header\n:footer: footer\n\nWith some text\n```\n","type":"content","url":"/cheat-sheet#cards","position":29},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Grids","lvl2":"Blocks"},"type":"lvl3","url":"/cheat-sheet#grids","position":30},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Grids","lvl2":"Blocks"},"content":"Cards can be arranged side by side, with the number of cards shown adapting to different screen sizes from small to large.\n\nWith a nice header\n\nAnd cool text\n\nAlso with a nice header\n\nWithout cool text\n\nMarkdown syntax\n:::{grid} 1 1 2 2\n```{card} With a nice header\nAnd cool text\n```\n```{card} Also with a nice header\nWithout cool text\n```\n:::\n","type":"content","url":"/cheat-sheet#grids","position":31},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Admonitions"},"type":"lvl2","url":"/cheat-sheet#admonitions","position":32},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Admonitions"},"content":"You can add special blocks that are highlighted in the text. See, for example, the warning below.\n\nThis is a warning without icon\n\nHere is a warning\n\nMarkdown syntax```{warning} This is a warning without icon\n:class: dropdown\n:open: true\n:icon: false\nHere is a warning\n```\n\nThere are different variants such as:\n\ntip\n\nadmonition\n\nwarning\n\nnote\n\nobjective\n\nUsing \n\nplugins you can add your own custom admonitions:Made for our [physics book](https://freekpols.github.io/Mechanica/) which includes experiments.","type":"content","url":"/cheat-sheet#admonitions","position":33},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Exercises","lvl2":"Admonitions"},"type":"lvl3","url":"/cheat-sheet#exercises","position":34},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl3":"Exercises","lvl2":"Admonitions"},"content":"A special case is the exercises which can be labelled and can come with a solution that is linked to the exercise:\n\nExercise 1\n\nCalculate 4+2\n\nSolution to \n\nExercise 1\n\n6\n\nMarkdown syntax```{exercise} Exercise 1\n:label: ex_opdr_1\n\nCalculate $4+2$\n```\n\n```{solution} ex_opdr_1\n:class: dropdown\n\n6\n```","type":"content","url":"/cheat-sheet#exercises","position":35},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Figures"},"type":"lvl2","url":"/cheat-sheet#cheat-sheet-figures","position":36},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Figures"},"content":"A site/book naturally needs figures. There are roughly two ways to add a figure:\n\nQuick figure, without formatting options![](path/to/figure)\n\nBetter way with more control:\n\n\n\nFigure 1:With a nice caption\n\nMarkdown syntax```{figure} https://github.com/rowanc1/pics/blob/main/sunset.png\n:label: fig_sunset\n:width: 70%\n:align: center\n\nWith a nice caption\n```\n\nHere we used figures hosted online, but you can also add figures to a folder (e.g., called figures), and then use a relative path (e.g. ../figures/sunset.png).","type":"content","url":"/cheat-sheet#cheat-sheet-figures","position":37},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"YouTube"},"type":"lvl2","url":"/cheat-sheet#youtube","position":38},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"YouTube"},"content":"To embed YouTube videos on the site, you need the embed YT link. The code is then:\n\n\n\nA super fun video from the project \n\nShow the Physics\n\nMarkdown syntax```{iframe} https://www.youtube.com/embed/YDBr1Lof_mI?si=thWYK9MFi5QJv-tW\n:width: 80%\n:align: center\n\nA super fun video from the project [Show the Physics](https://interactivetextbooks.tudelft.nl/showthephysics)\n```\n\nYT in pdf\n\nEmbedded YT videos are not included in the PDF. A solution could be to include our \n\nplugin which creates a QR code that links to the video, as well as a thumbnail of the video - taken from YT.\n\nUsing the same iframe directive, you can also embed other web content, like quizzes from a repository:","type":"content","url":"/cheat-sheet#youtube","position":39},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"References & Links"},"type":"lvl2","url":"/cheat-sheet#cheatsheet-ref","position":40},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"References & Links"},"content":"You can include \n\nlinks like this.\nWith the markdown syntax: [text](link).\nlink can take a number of forms including,\n\nA URL\n\nA label prepended with a # (like in the examples of figures and equations here)\n\nA references to an external MyST project, using xref:\n\nA wikipedia page, using wiki:\n\nA DOI, using doi:\n\nMyST lets you add labels to \n\nany block of content by adding a label like (label)= before the block.\nThis is a great way to reference things like sections or paragraphs, which don’t otherwise have a label like figure directives or equations.\n\nIf you leave the text empty, appropriate link text will be automatically generated.\nWhen referencing objects with a name or number, you can use {name} and {number} (or %s) in text to use the name and number in the link text respectively.\n\nBelow are a few examples of references,\n\nThis is a \n\nhyperlink\n\nThis is a reference to equation \n\n(1)\n\nThis is a reference to a table \n\nTable 3 or \n\nTab. 3\n\nThis is a reference to a figure \n\nFigure 1 or \n\nFig. With a nice caption\n\nThis is a reference to an external MyST project \n\nExternal MyST projects\n\nThis is a reference to a DOI \n\nPols (2021) or \n\nPols (2021)\n\nThis is a reference to a Wikipedia page \n\nProject Jupyter\n\nThis is a reference to a GitHub pull request \n\njupyter​-book​/mystmd​#2106\n\nThis is a reference to a file in GitHub \n\nREADME.md\n\nMarkdown syntax- This is a [hyperlink](https://nos.nl)\n- This is a reference to equation [](#eq_newton)\n- This is a reference to a table [](#tl_example) or [Tab. %s](#tl_example)\n- This is a reference to a figure [](#fig_sunset) or [**Fig. {name}**](#fig_sunset)\n- This is a reference to an external MyST project [](xref:myst-guide/external-references#myst-xref)\n- This is a reference to a DOI [](https://doi.org/10.1088/1361-6552/abf208) or [](doi:10.1088/1361-6552/abf208)\n- This is a reference to a Wikipedia page [](wiki:Project_Jupyter)\n- This is a reference to a GitHub pull request [](https://github.com/jupyter-book/mystmd/pull/2106)\n- This is a reference to a file in GitHub [](https://github.com/jupyter-book/mystmd/blob/d39d9d68b2d67002771d95a87b56334d2d853585/README.md?#L1-L5)\n\nTip\n\nNote how many of the references have dynamic tooltips.","type":"content","url":"/cheat-sheet#cheatsheet-ref","position":41},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Citations"},"type":"lvl2","url":"/cheat-sheet#citations","position":42},{"hierarchy":{"lvl1":"Markdown Cheat Sheet","lvl2":"Citations"},"content":"You can cite entries in a Bibtex bibliography using  @.\nThe bibliography file is named reference.bib and located at the project’s root directory.\n\nFeynman et al. (1965)\n\nFeynman et al. (1965, p. 750)\n\nMarkdown syntax- @feynman1965feynman\n- @feynman1965feynman [p. 750]\n\nThis is an auto-numbered footnote definition.","type":"content","url":"/cheat-sheet#citations","position":43},{"hierarchy":{"lvl1":"Advanced start 🌶"},"type":"lvl1","url":"/advanced-start","position":0},{"hierarchy":{"lvl1":"Advanced start 🌶"},"content":"Updated: 03 Nov 2025\n\nThe Jupyter Book and MyST CLIs both include tools to help get started writing quickly. You might want to follow this approach if:\n\nYou are already familiar with using Markdown dialects to build documents and websites\n\nYou have previously used Jupyter Book 1\n\nYou are comfortable working with command line tools and reading documentation\n\nYou don’t like waiting for GitHub Actions to see updates to your book as you edit it\n\nThe \n\nMyST Markdown guide will be a valuable resource if you follow this route.","type":"content","url":"/advanced-start","position":1},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Install Jupyter Book"},"type":"lvl2","url":"/advanced-start#install-jupyter-book","position":2},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Install Jupyter Book"},"content":"There are \n\na number of options for installing Jupyter Book.\nTwo common methods are using pippip install \"jupyter-book>=2.0.0\"\n\nor npmnpm install -g \"jupyter-book@>=2.0.0-a0\"\n\nHint\n\nNote the version specifications, which ensure the MyST-based Jupyter Book 2 is installed, not the Sphinx-based Jupyter Book 1.","type":"content","url":"/advanced-start#install-jupyter-book","position":3},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Initialise a project with CLI"},"type":"lvl2","url":"/advanced-start#initialise-a-project-with-cli","position":4},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Initialise a project with CLI"},"content":"To initialise a Jupyter Book project, use the CLIjupyter-book init\n\nThis will create a basic book, including the myst.yml file.\nYou can serve your book locallyjupyter-book start\n\nOpen \n\nhttp://localhost:3000 in your browser to see the output.","type":"content","url":"/advanced-start#initialise-a-project-with-cli","position":5},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Edit the content"},"type":"lvl2","url":"/advanced-start#edit-the-content","position":6},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Edit the content"},"content":"You can edit the content files in the content directory using your text editor and see the output immediately updated in your browser at the local server address (you may need to refresh the page when changes are made).\n\nYou may want to follow \n\nthe lessons here or experiment yourself with the \n\nMyST Markdown guide.","type":"content","url":"/advanced-start#edit-the-content","position":7},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Deploy to GitHub pages"},"type":"lvl2","url":"/advanced-start#deploy-to-github-pages","position":8},{"hierarchy":{"lvl1":"Advanced start 🌶","lvl2":"Deploy to GitHub pages"},"content":"The CLI can also prepare a GitHub workflow to deploy your book to GitHub Pages, similar to the template.jupyter-book init --gh-pages\n\nThe command will print instructions to finish setting up GitHub Pages.","type":"content","url":"/advanced-start#deploy-to-github-pages","position":9},{"hierarchy":{"lvl1":"Gallery"},"type":"lvl1","url":"/gallery","position":0},{"hierarchy":{"lvl1":"Gallery"},"content":"Updated: 01 Nov 2025\n\nJupyter Book 2 technology has been applied across a wide range of use cases, including curricula vitae, official educational textbooks, student portfolios, lab manuals, and technical documentation.\n\nBelow is a gallery showcasing examples of such outputs.\n\nThe Turing Way handbook to reproducible, ethical and collaborative data science.\n\nThe Turing Way is an open science, open collaboration, and community-driven project. We involve and support a diverse community of contributors to make data science accessible, comprehensible and effective for everyone.\n\n\n\nThe Turing Way project illustration by Scriberia. Zenodo. \n\n@https://​doi​.org​/10​.5281​/ZENODO​.3332807\n\nMyst Official Documentation\n\nMyST is an ecosystem of open-source, community-driven tools designed to revolutionize scientific communication. Our powerful authoring framework supports blogs, online books, scientific papers, reports and journals articles.\n\n\n\nLive graphs can be embedded directly in your documentation or articles with computation backed by Jupyter or JupyterLite – running locally, on Binder, or directly in your browser.\n\nIntroducing Classical Mechanics & Special Relativity\n\nThis book provides an introduction for freshman students into the world of classical mechanics and special relativity theory\n\n\n\nScientific Python\n\nThe scientific Python ecosystem is a loose federation of community-developed and -owned Python projects widely used in scientific research, technical computing, and data science. The scientific Python community of contributors and maintainers are employed by a variety of universities, research labs, and companies.\n\n\n\nProject Pythia\n\nProject Pythia is the education working group for Pangeo and is an educational resource for the entire geoscience community. Together these initiatives are helping geoscientists make sense of huge volumes of numerical scientific data using tools that facilitate open, reproducible science, and building a community of practice around these goals.\n\nProject Pythia is a home for Python-justified learning resources that are open-source, community-owned, geoscience-focused, and high-quality.\n\n\n\nIRSA Tutorials\n\nIRSA (Infrared Science Archive) provides a variety of tutorials to help users understand and utilize the data and tools available through the archive.\n\n\n\nIRSA Tutorials logo","type":"content","url":"/gallery","position":1},{"hierarchy":{"lvl1":"Set up a new repository"},"type":"lvl1","url":"/setup","position":0},{"hierarchy":{"lvl1":"Set up a new repository"},"content":"Updated: 03 Nov 2025\n\nThe instructions on this page guide you through the process of:\n\nmaking your own book by creating a (new) GitHub repository from a template repository,\n\nmaking an edit to your book,\n\n“building” your book and viewing it in a web browser via a local server and/or online with GitHub pages.\n\nTip\n\nWe recommend you complete the lessons in this workshop by installing Jupyter Book on your computer and building the book using a command line interface (CLI). This is referred to as the local approach. If you are unable to use the CLI, or do not wish to, tt is possible to complete this workshop by working entirely in the browser. This is referred to as the online approach. When instructions are different for each approach, tab sets will be used, as illustrated here:\n\nInstructions specific for those working using a CLI and Jupyter Book installed “locally.”\n\nInstructions specific for those working online using tools available via github.com (e.g., the github.dev IDE) and GitHub Actions workflows.","type":"content","url":"/setup","position":1},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Create a repository"},"type":"lvl2","url":"/setup#create-a-repository","position":2},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Create a repository"},"content":"Follow these instruction to use the GitHub template repository to create your own book for this workshop:\n\nGo to the \n\nrepository for this book\n\nClick the green button use this template and click create a new repository.\n\nChoose a proper name of your repository (this will be also part of your URL!) and choose the option public.\n\nIn your repository, click on settings and in the left menu on Pages and choose Github Actions\n\nTip\n\nGitHub Actions will be covered later in this workshop, so if you have no idea what this is, don’t worry!\n\n\n\nFigure 1:Follow these steps to create your own repository from the template.\n\nClick on code and click on the gear-icon (near About) at the right site of the page.\n\nCheck the box Use your GitHub Pages website.\n\nGo to Actions in the top menu, click on the (red) initial commit and click re-run all jobs\n\nThe book will now be deployed again - where now it can actually load GitHub pages.\n\n\n\nFigure 2:Follow these steps to create your own GH Pages site from the template.","type":"content","url":"/setup#create-a-repository","position":3},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"View your book online"},"type":"lvl2","url":"/setup#view-your-book-online","position":4},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"View your book online"},"content":"The previous stps set up your repository with GitHub Pages, which a GitHub Actions workflow to automatically build your book (a website) and deploy it online. The URL of your book is based on your GitHub username:https://USERNAME.github.io/workshop-template\n\nThis is, in fact, how the website for this document is created:\n\nhttps://​jupyter​-book​.github​.io​/workshop​-template/\n\nYou can also find the link easily from you GitHub repository home page under the “About” section on the right-hand side (illustrated in \n\nFigure 4).\n\nThe home page of your new book website should look like \n\nFigure 3.\n\n\n\nFigure 3:The home page of your new site, which you can visit once the GitHub Action workflow has successfully completed.\n\nTip\n\nCheckout the content on your mobile phone as well! It just looks amazing.","type":"content","url":"/setup#view-your-book-online","position":5},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Repo folder structure"},"type":"lvl2","url":"/setup#repo-folder-structure","position":6},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Repo folder structure"},"content":"Your GitHub repository may look similar to the one shown in \n\nFigure 4; note the following directories:\n\ncontent: the source files of your book (in markdown or jupyter notebook format),\n\ncontent/figures: the folder which includes figures for your book,\n\ncontent/lessons: the folder which includes the lessons of this workshop,\n\n.github/workflows: the folder which includes the GitHub Actions (automated workflows) to build and deploy your book,\n\ncss: a folder which includes a custom css file to change the layout of your book,\n\nA myst.yml file which defines the structure and settings of your Jupyter Book.\n\n\n\nFigure 4:Illustration of repository folder structure.\n\nAs proceed through the workshop you will edit the files in your new repository.","type":"content","url":"/setup#repo-folder-structure","position":7},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Edit the book"},"type":"lvl2","url":"/setup#edit-the-book","position":8},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Edit the book"},"content":"You have a number of options for making changes to the book’s source and seeing how they affect the output.\n\nClone the repository to your local machine using Git.git clone git@github.com:<github_user_name>/workshop-template.git\n\nInstall Jupyter Book, using the virtual environment manager of your choice (all of the tools used today can easily be handled using pip)pip install -r requirements.txt\n\nMake a change to one of the files in the content directory using a text editor.\n\n(optional) Commit the the change using Git and push it to the remote repository (this will trigger the GitHub Actions workflow and rebuild the website, which can be viewed at the same URL described above). If you go back to your repository and click on the Actions tab you will see that the workflow is running to build and deploy your book. After a few minutes, you can refresh your book page and see your changes!\n\nBuild the book from source and serve it locally.jupyter book start\n\nPreview the book in your browser at \n\nhttp://localhost:3000\n\nTip\n\nThe localhost address may be different than 3000 (check the CLI output).\n\nOnce the MyST server is running, it will automatically update as you make changes to the source.\n\nTo work online, you must “edit” a file by making a commit using GitHub’s online tools:\n\nClick on the index.md file in the Content folder\n\nClick on the drop down icon next to the pencil icon and choose open in github.dev This will start the GitHub development environment where you can edit the files directly in your browser.\n\nEdit the file by replacing the names with your own and commit your changes, see \n\nFigure 5\n\n\n\nFigure 5:Working directly in the GitHub development environment.\n\nNow, if you go back to your repository and click on the Actions tab you will see that the workflow is running to build and deploy your book. After a few minutes, you can refresh your book page and see your changes!","type":"content","url":"/setup#edit-the-book","position":9},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Create a PDF export"},"type":"lvl2","url":"/setup#create-a-pdf-export","position":10},{"hierarchy":{"lvl1":"Set up a new repository","lvl2":"Create a PDF export"},"content":"A clear advantage of JB2 over JB1 is the ability to easily create a high quality PDF export of your book (as well as other formats). In a \n\nlater lesson of this workshop, we will build a PDF locally and/or modify the GitHb Action workflow to automatically create a PDF export of your book using Typst when changes are pushed changes to your repository.","type":"content","url":"/setup#create-a-pdf-export","position":11},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals"},"type":"lvl1","url":"/firstedit","position":0},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals"},"content":"Updated: 03 Nov 2025\n\n","type":"content","url":"/firstedit","position":1},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Anatomy of a Jupyter Book"},"type":"lvl2","url":"/firstedit#anatomy-of-a-jupyter-book","position":2},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Anatomy of a Jupyter Book"},"content":"A Jupyter Book is a collection of files and folders that together make up the content and structure of your book.\nJupyter Book 2 (JB2) supports both \n\nMarkdown files and \n\nJupyter Notebooks as content sources.\nThe structure of the book is specified in the myst.yml file, which is located in the root directory of your book.\nThis file contains information about the title, author, and other metadata of the book, as well as documents and its structure to build the book itself.\n\n# See docs at: https://mystmd.org/guide/frontmatter\nversion: 1\nproject:\n  id: 7204695b-7485-4989-863c-16cf6e4db155\n  title: Jupyter Book 2 Workshop Template\n  description: This description goes in the preface of the pdf output. \n  # keywords: []\n  authors:\n    - name: Freek Pols\n    - name: Luuk Fröling\n    - name: Robert Lanzafame\n    - name: Kirstie Whitaker\n    - name: Jim Madge\n  license:\n    content: CC-BY-4.0\n\nProgram 1:The head of this book’s myst.yml\n\nOfficial documentation\n\nSee \n\nhere for a full explanation of the structure and TOC and \n\nhere for more the website options.","type":"content","url":"/firstedit#anatomy-of-a-jupyter-book","position":3},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Markdown"},"type":"lvl2","url":"/firstedit#markdown","position":4},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Markdown"},"content":"Markdown is a simple markup language: plain text that is formatted with small pieces of ‘code’. This allows you to create rich, interactive books that combine text, code, and visualizations. This text can then be quickly exported to various other formats such as PDF, Word, HTML, etc.\n\n\n\nDocuments made in MyST Markdown can be converted to many different formats. These can be saved as JSON, or rendered to a website (like this one!) or any number of formats including \n\nPDF & LaTeX, \n\nWord, \n\nReact, or \n\nJATS. Picture taken from the MYST documentation .","type":"content","url":"/firstedit#markdown","position":5},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Your first change"},"type":"lvl2","url":"/firstedit#your-first-change","position":6},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Your first change"},"content":"As explained in the previous chapter, your files are on GitHub and the template ensures the book is built.\nYou can make changes directly to the files online in GitHub, and create or upload new files.\n\nSome files are already present in the template book.\nThe folder structure is shown below\n\n    - file: index.md                      # the landing page\n    - file: content/1_intro.md\n    - file: content/2_cheat_sheet.md\n    - file: content/lessons/your_turn.md          # dropdown menu\n      children:\n        - file: content/lessons/0_setup.md\n        - file: content/lessons/1_firstedit.md\n        - file: content/lessons/1_landingpage.md\n        - file: content/lessons/2_nextstep.md\n          children:\n            - file: content/lessons/2a_plugins.md\n        - file: content/lessons/reuse.md\n        - file: content/lessons/executable.md\n        - file: content/lessons/5_workflows.md\n        - file: content/lessons/6_pdfoverview.md\n          children:\n            - file: content/lessons/6a_myst.md\n            - file: content/lessons/6b_pdfgeneration.md\n            - file: content/lessons/6c_pdfoutput.md\n            # - file: content/lessons/6d_typsttemplate.md\n        # - file: content/lessons/7_styling.md\n        - file: content/lessons/8_init.md\n\n    - file: content/advanced_start.md\n    - file: content/software.md\n\nProgram 2:The Table of Contents (ToC) for this book.\n\nWe will now make a small change to one of the files and then look at the result of that change.\n\nYour first change\n\nNavigate to the file Content/Lessons/1_firstedit.md. Then click on the pencil on the right (edit this file).\n\nChange the text after the #. This is the title of the file.\n\n\n\nChoose your file, click on edit and make changes. Ready? Commit your changes to your repository and see the output.\n\nOptionally, make other changes in the text editor and when you’re done, commit your changes to the “remote repository” by clicking the green Commit changes button.\n\nThe book will now be rebuilt. Once that’s done, you can view the result on the GitHub page.\n\nNavigate to the file Content/Lessons/1_firstedit.md and open the file.\n\nChange the text after the #. This is the title of the file.\n\nOptionally, make other changes in the text editor.\nCheck the results by running myst start in the CLI and opening the local server http://localhost:3000/.\nWhen you’re done, commit your changes to the “remote repository”.\n\nThe book will now be rebuilt.\nOnce that’s done, you can view the result on the GitHub page as well.\n\nCommit summary\n\nIf you are working with multiple people in GitHub, or on a large project yourself, it is wise to give the commit a recognizable title (commit message) and optionally add a summary (extended description) of exactly what was changed, see also \n\nthis more elaborative description.\nThis way, you can detect and undo any errors early. You can also explain why certain changes were made.","type":"content","url":"/firstedit#your-first-change","position":7},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Adding a page"},"type":"lvl2","url":"/firstedit#adding-a-page","position":8},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Adding a page"},"content":"The \n\nTable of Contents defines the structure of your Jupyter Book.\nItems in your myst.yml’s toc will be added to the book’s table of contents.\nMarkdown, TeX and Jupyter Notebook files will be rendered as pages (in the case of a website) or chapters (in the case of a document).\n\nTo add a new page from a Markdown file,\n\nCreate a new markdown file\n\nAdd some content to the file\n\nInclude in the \n\nToC\n\nAdd a new page\n\nCreate a new markdown file\n\nnavigate to the folder where you want to include the sourcefile\n\nclick add file / + Create new file\n\ncreate a clear name for the file and use the .md extension (e.g. newfile.md)\n\nCreate a \n\nH1 heading\n\nuse for the header # and include the title\n\ncommit your changes\n\nInclude the file in the \n\nToC.\n\nnavigate to the myst.yml file in the root\n\nat the right location in your book, include the path to your file (e.g. - file: content/lessons/newfile.md)\n\ncommit your changes and check the output on GitHub pages.\n\nCreate a new markdown file\n\nnavigate to the folder where you want to include the sourcefile\n\ncreate a new file\n\ncreate a clear name for the file and use the .md extension (e.g. newfile.md)\n\nCreate a \n\nH1 heading\n\nuse for the header # and include the title\n\nsave your file\n\nInclude the file in the \n\nToC.\n\nnavigate to the myst.yml file in the root folder\n\nat the right location in your book, include the path to your file (e.g. - file: content/lessons/newfile.md)\n\nsave your changes and check the out on your local server.","type":"content","url":"/firstedit#adding-a-page","position":9},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Using Headings"},"type":"lvl2","url":"/firstedit#using-headings","position":10},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Using Headings"},"content":"Similarly to how your table of contents gives structure to your Jupyter Book,\nwithin a page you can build structure using headings.\nYou can use levels of headings from 1 to 6 to structure a page.\n\nNote\n\nIn the \n\nbook theme, headings are shown, and can be used to navigate a page, in the Contents menu at the right of a page.\n\nAdd headings to your new page\n\nNavigate to the Markdown file you added to the book in \n\nExercise 2.\nYou have already added a level one heading, the title of the page.\n\nAdd headings to represent the following structure.\nRefer to the \n\ncheat sheet if you need a reminder on the syntax.\n\nAnimals\n\nDogs\n\nBearded Collie\n\nIrish Wolfhound\n\nCats\n\nCalico\n\nTabby\n\nHippos\n\nCommon\n\nPygmy\n\nFood\n\nSoup\n\nCarrot and coriander\n\nMiso\n\nGazpacho\n\nSalad\n\nCaesar\n\nGreek\n\nNiçoise","type":"content","url":"/firstedit#using-headings","position":11},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Essential typography"},"type":"lvl2","url":"/firstedit#essential-typography","position":12},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Essential typography"},"content":"You should now be confident making changes locally or through the GH IDE.\nTry making the changes indicated in the following exercise using the solution directive below.\nRefer to the \n\ncheat sheet if you need a reminder on the syntax.\n\nTypography\n\nMake this line bold.\n\nMake this line italic.\n\nPut these items in an unordered list,\n\nElm\nSycamore\nOak\nBeech\n\nPut these items in an ordered list,\n\nHydrogen\nHelium\nLithium\nBeryllium\nBoron\nCarbon\n\nPut a line break between this sentence. And this sentence.\n\nMake the following line an equation with a label,\n\nF = m a\n\nAnd reference that equation here.\n\nSolution to \n\nExercise 4\n\nOptionally you can put your answers here.\n\nHint\n\nRemember, new lines in a Markdown file don’t create new paragraphs in the output.\nSee the \n\ncheat sheet for a reminder.","type":"content","url":"/firstedit#essential-typography","position":13},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Next steps"},"type":"lvl2","url":"/firstedit#next-steps","position":14},{"hierarchy":{"lvl1":"Jupyter Book Fundamentals","lvl2":"Next steps"},"content":"Going further\n\nTry making some more changes to the page you created in \n\nExercise 2.\nFind an element in the \n\ncheat sheet or \n\nMyST Markdown guide that you haven’t used yet, for example abbrevitions or a code block, and try adding it.\nRemember to check the result regularly.\n\nhttps://​mystmd​.org​/guide/","type":"content","url":"/firstedit#next-steps","position":15},{"hierarchy":{"lvl1":"Create your own landing page"},"type":"lvl1","url":"/landingpage","position":0},{"hierarchy":{"lvl1":"Create your own landing page"},"content":"","type":"content","url":"/landingpage","position":1},{"hierarchy":{"lvl1":"Create your own landing page","lvl2":"Create your landing page"},"type":"lvl2","url":"/landingpage#create-your-landing-page","position":2},{"hierarchy":{"lvl1":"Create your own landing page","lvl2":"Create your landing page"},"content":"a great way to welcome your visitors and provide clear directions.\n\nCheck out the full documentation\n\nA landing page is the first page that a visitor of your website will see. Hence, you want to make sure it has the right vibe and contains the right information. As in books, the cover can be set differently than its content.\n\nIn Jupyter Book you have the option to:\n\ncreate a custom \n\nlanding page using a split image.\n\ncreate sections using \n\nblocks\n\nhide \n\ntable of contents\n\nadd a \n\ncustom footer.\n\nadd \n\ncards in a grid to link to specific pages or other websites.\n\n","type":"content","url":"/landingpage#create-your-landing-page","position":3},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Hide outline and table of contents","lvl2":"Create your landing page"},"type":"lvl3","url":"/landingpage#hide-outline-and-table-of-contents","position":4},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Hide outline and table of contents","lvl2":"Create your landing page"},"content":"To use the full width of the page, you can hide the outline and table of contents by including the following in your index.md (if that is the landing page):---\nsite:\n  hide_outline: true\n  hide_toc: true\n  hide_title_block: true\n---\n\nAs we make use of the \n\npage-last-updated plugin, we also set no-update-date: true to hide the date of the last update.\n\n","type":"content","url":"/landingpage#hide-outline-and-table-of-contents","position":5},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Create specific blocks","lvl2":"Create your landing page"},"type":"lvl3","url":"/landingpage#create-specific-blocks","position":6},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Create specific blocks","lvl2":"Create your landing page"},"content":"You can create specific blocks which are styled differently. For instance, we used split-image at the top of the page. And justified for the \n\nsection on hiding the outline and table of contents.\n\nTo create a split image on your landing page, you can use the split-image directive. This allows you to have an image on one side and text on the other side. You can customize the content and layout to fit your needs, e.g. include a button that links to some other page or website.\n+++ { \"kind\": \"split-image\" }\n\n# Create your landing page\n\na great way to welcome your visitors and provide clear directions.\n\n{button}`Check out the full documentation <https://mystmd.org>`\n\n![](../figures/delft.png)\n\n+++\n\nIn a similar we used the justified block which creates a block that spans the full width of the screen:+++ {\"kind\": \"justified\"}","type":"content","url":"/landingpage#create-specific-blocks","position":7},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Cards","lvl2":"Create your landing page"},"type":"lvl3","url":"/landingpage#cards","position":8},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Cards","lvl2":"Create your landing page"},"content":"Often cards are used at the landing page to link to specific pages or websites. For instance, using the justified:\n\n","type":"content","url":"/landingpage#cards","position":9},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Get started","lvl2":"Create your landing page"},"type":"lvl3","url":"/landingpage#get-started","position":10},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Get started","lvl2":"Create your landing page"},"content":"📖 Manual\n\nRead the manual where we describe the process of building and publishing a JupyterBook, including the necessary tools and resources.\n\n✍ Starterkit\n\nA TU Delft starterkit to help you get started with creating your own JupyterBook\n\n📈 Jupyter Book\n\nSee the official Jupyter Book documentation for more information on how to use Jupyter Book and its features.\n\n🌅 Gallery\n\nSee the collection of interactive textbooks published\n\n\n\n","type":"content","url":"/landingpage#get-started","position":11},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Gallery of landing pages","lvl2":"Create your landing page"},"type":"lvl3","url":"/landingpage#gallery-of-landing-pages","position":12},{"hierarchy":{"lvl1":"Create your own landing page","lvl3":"Gallery of landing pages","lvl2":"Create your landing page"},"content":"Below is a selection of landing pages created by the Jupyter Book community. You can use these for inspiration when creating your own landing page.\n\nmystmd\n\nThe official documentation of MyST\n\nJupyter Book\n\nThe official documentation of Jupyter Book\n\npersonal website\n\nA personal website\n\nEducational book\n\nLanding page of an educational book.","type":"content","url":"/landingpage#gallery-of-landing-pages","position":13},{"hierarchy":{"lvl1":"More content"},"type":"lvl1","url":"/nextstep","position":0},{"hierarchy":{"lvl1":"More content"},"content":"Updated: 03 Nov 2025\n\nIn \n\nJupyter Book Fundamentals we covered the basics of Jupyter Book structure and writing text content in markdown.\nHowever, Jupyter Book can go far beyond basic text formatting and has tools to help you share information with figures, videos, special blocks, interactive elements and advanced cross-referencing.\nIn this lesson we will look at some of these features that elevate your book over a plain-text document.","type":"content","url":"/nextstep","position":1},{"hierarchy":{"lvl1":"More content","lvl2":"Directives and roles"},"type":"lvl2","url":"/nextstep#directives-and-roles","position":2},{"hierarchy":{"lvl1":"More content","lvl2":"Directives and roles"},"content":"This lesson will make use of \n\nroles and directives.\nThese have a similar syntax, and are used to extend the basic markdown features.\nThe main difference is that roles are written in-line and take a single argument, whereas directives are multi-line containers which may have multiple arguments and options.\n\nBoth directives and roles use “fences”, which are either (at least) three colons ::: or backticks ```.\nYou can use more colons or backticks to nest directives.\nThe \n\nMyST documentation explains the syntax, nesting and the difference between colons and backticks in more detail.\n\nNote\n\nIf there is a feature you would like to add to your project,\nyou could create a new role or directive in a plugin to extend the behaviour of MyST.","type":"content","url":"/nextstep#directives-and-roles","position":3},{"hierarchy":{"lvl1":"More content","lvl2":"Images and figures"},"type":"lvl2","url":"/nextstep#images-and-figures","position":4},{"hierarchy":{"lvl1":"More content","lvl2":"Images and figures"},"content":"The quickest way to include an image is with the Markdown notation ![alt text](url-or-path) as done below![External image](https://polslab.tnw.tudelft.nl/figures/training.JPG)\n\nresulting in\n\n\nHowever, this gives us limited options to customize the figure.\nMoreover, we are dependent of a stable external URL.\nWe can include our own figures and add more options using the \n\nfigure directive.\n\nIf we want to add a figure to our book, we can use the URL of an external website (as in the figure above).\nHowever, this carries the risk that the figure will no longer be visible if it is moved from its location.\nIt is therefore better to have the figure as a local source file where you build the book.\nWe will do this by adding an image file to your git repository.\n\nInclude a figure\n\nOn GitHub, under the code tab…\n\nNavigate to content/figures and click on add file \\rightarrow Upload files.\n\n\n\nFigure 1:Add a file in the folder by choosing Upload files\n\nChoose the figure you want to add (remember the file name!).\n\nCommit your changes to GitHub (the file will be uploaded).\n\nNavigate to the book folder and open intro.md and click edit this file.\n\nCopy the code below into that file, and change the figure name to your own figure’s name.``` {figure} figures/incl_fig.PNG\n:width: 50%\n:name: fig_myfirstfigure\nadd file in the folder\n```\n\nCommit your changes and view the result on GitHub pages.\n\nPut the image file you want to include to the content/figures folder on your computer.\n\nNavigate to the book folder and open intro.md.\n\nCopy the code below into that file, and change the figure name to your own figure’s name.``` {figure} figures/incl_fig.PNG\n:width: 50%\n:name: fig_myfirstfigure\nadd file in the folder\n```\n\nCommit your changes and view the results.\n\nHint\n\nRemember to add your image to the repository with git add.\n\nWarning\n\nThe filename is case sensitive.\nSo it matters whether your extension is .png or .PNG.\nYou can also use .* to avoid this issue, the system will then pick the right extension where the best options is chosen first (e.g. .gif over .png, and .svg over .jpg).\nThis also avoids conversion issues for pdf output of non-static or non-supported formats\n\nTip\n\nYou can find more information about figure options \n\nin the MyST documentation.\n\nYou can position figures in different places (left / center / right / margin), adjust the size, add a caption, etc..\nCheck the documentation above and try out the different settings.","type":"content","url":"/nextstep#images-and-figures","position":5},{"hierarchy":{"lvl1":"More content","lvl2":"Embed a video (from YouTube)"},"type":"lvl2","url":"/nextstep#embed-a-video-from-youtube","position":6},{"hierarchy":{"lvl1":"More content","lvl2":"Embed a video (from YouTube)"},"content":"We can embed videos hosting platforms like YouTube or Vimeo using the \n\niframe directive.\nFor example, the following code embeds a video about Markdown,```{iframe} https://www.youtube.com/embed/dhzrlXzYOlU?si=n2U0HSJyotjp-r93\n:width: 80%\n\nPurves et al. - Jupyter Book 2 0 – A Next Generation tool for sharing for Computational Content\n```\n\nresulting in\n\n\n\nPurves et al. - Jupyter Book 2 0 – A Next Generation tool for sharing for Computational Content\n\nNote\n\nThe use of iframe is not limited to videos.\nYou can embed content from other websites that support iframe embedding.\n\nNote\n\nYou can also use the figure directive to include a video from a local file, just like with images.\n\nTip\n\nThere is a \n\nplugin available that converts the YouTube clip in a qr code and a thumbnail for pdf exports.\n\nEmbed your own video\n\nEmbed a video of your choice using either the iframe or video directive.\nYou can use a YouTube video or any other video that supports embedding.","type":"content","url":"/nextstep#embed-a-video-from-youtube","position":7},{"hierarchy":{"lvl1":"More content","lvl2":"Displaying code"},"type":"lvl2","url":"/nextstep#displaying-code","position":8},{"hierarchy":{"lvl1":"More content","lvl2":"Displaying code"},"content":"You can display code using Markdown syntax.```language\ncode\n```\n\nfor example,``` python\nprint(\"Hello world!\")\n```\n\nrenders as,print(\"Hello world!\")\n\nYou can also use the \n\ncode directive which will render the code in a block and has features line line numbers and captions.\n\nAdd a code block\n\nTake the following Python code snippet and put it in a code block with\n\nPython syntax highlighting\n\nIndicate the file name fibonacci.py\n\nAdd a caption explaining that this function returns the nth number in the Fibonacci seriesdef fib(n):\n    if n < 0:\n        return\n    if n in [0, 1]:\n        return n\n    else:\n        return fib(n-2) + fib(n-1)","type":"content","url":"/nextstep#displaying-code","position":9},{"hierarchy":{"lvl1":"More content","lvl2":"Diagrams"},"type":"lvl2","url":"/nextstep#diagrams","position":10},{"hierarchy":{"lvl1":"More content","lvl2":"Diagrams"},"content":"MyST supports displaying \n\nMermaid diagrams using the \n\nmermaid directive.\nMermaid let’s you create a number of different types of diagrams using plain text.\nThis is a great way to show diagrams in your book, while keeping the source easily editable in version control.\nFor example, the following directive```{mermaid}\nflowchart LR\n  Start --> Stop\n\n  A1([\"Novice\"]) --> B1\n  A2([\"I do know\"]) --> B2 & B1\n  B1([\"Expert\"])\n  B2([\"try\"])\n\n  A([\"Start\"]) --> B{\"Decision\"}\n  B --> C[\"Option A\"] & D[\"Option B\"]\n```\n\nRenders as,flowchart LR\n  Start --> Stop\n\n  A1([\"Novice\"]) --> B1\n  A2([\"I do know\"]) --> B2 & B1\n  B1([\"Expert\"])\n  B2([\"try\"])\n\n  A([\"Start\"]) --> B{\"Decision\"}\n  B --> C[\"Option A\"] & D[\"Option B\"]\n\nCreate a diagram\n\nCreate your own mermaid diagram.\nYou can create a diagram from scratch, consulting the syntax in the \n\nMermaid documentation,\nor copy \n\nan example","type":"content","url":"/nextstep#diagrams","position":11},{"hierarchy":{"lvl1":"More content","lvl2":"Admonitions"},"type":"lvl2","url":"/nextstep#admonitions","position":12},{"hierarchy":{"lvl1":"More content","lvl2":"Admonitions"},"content":"Admonitions can be used to separate text from the main text and highlight it appropriately.\nHere are a set of admonitions built in to Myst,\n\nNote\n\nThis is an note admonition\n\nImportant\n\nThis is an important admonition\n\nHint\n\nThis is an hint admonition\n\nSee Also\n\nThis is an seealso admonition\n\nTip\n\nThis is an tip admonition\n\nAttention\n\nThis is an attention admonition\n\nCaution\n\nThis is an caution admonition\n\nWarning\n\nThis is an warning admonition\n\nDanger\n\nThis is an danger admonition\n\nError\n\nThis is an error admonition\n\nCustom admonitions can also be created in a plugin, but hiding the icon and adding your own icon in the title is a quick way to get a custom look.\n\nAdmonitions\n\nUse an appropriate admonition to contain the following paragraphs.\n\nHand wash only\n\nSyntax error\n\nBeware of the leopard","type":"content","url":"/nextstep#admonitions","position":13},{"hierarchy":{"lvl1":"More content","lvl2":"Tabs, cards, grids"},"type":"lvl2","url":"/nextstep#tabs-cards-grids","position":14},{"hierarchy":{"lvl1":"More content","lvl2":"Tabs, cards, grids"},"content":"MyST has a number of features for arranging and organising content, you have already seen some of these following these lessons.\n\nDropdowns, Grids, Tabs and Cards\n\nAsides, Margin Content, and Sidebars\n\nBlocks and Comments\n\nTabs can be used to separate content into different sections that can be viewed by clicking on the tab headers.\nThey are useful when you want to present a set of mutually exclusive options.:::: {tab-set}\n::: {tab-item} Tab 1\nContent for Tab 1\n:::\n::: {tab-item} Tab 2\nContent for Tab 2\n:::\n::::\n\nRenders as,\n\nContent for Tab 1\n\nContent for Tab 2\n\nCreate a tab set for installing MyST\n\nPut the following instructions for installing MyST into a tab set,\nsplitting instructions for pip and npm into different tabs.\n\nInstall MyST\n\nUsing pip: pip install mystmd\n\nUsing npm: npm install -g mystmd\n\nFetching images from someone else’s site also puts strain on their web server, which they may not appreciate.","type":"content","url":"/nextstep#tabs-cards-grids","position":15},{"hierarchy":{"lvl1":"Plugins 🌶"},"type":"lvl1","url":"/a-plugins","position":0},{"hierarchy":{"lvl1":"Plugins 🌶"},"content":"Updated: 30 Oct 2025\n\nPlugins allow you to extend the functionality of Jupyter Book.\nIn this workshop-template, we make use of a single plugin:\n\n  plugins:\n    - https://github.com/TUD-JB-Templates/JB2_plugins/releases/download/experiment/experiment.mjs\n    - https://github.com/jupyter-book/myst-plugins/releases/download/page-last-updatedv1.1/page-last-updated.mjs\n  \n\nProgram 1:We make use of plugins in this workshop-template.\n\nThis plugin allows you to create a custom admonition:Have two coins A and B touching and a third coin (C) lengthwise at a few cm distance.\nThen shoot coin C towards B while pressing B down with your finger.\nIf coin A and coin B touch, then the momentum transfers very well to coin A even though B is not able to move.\nThe transmission mechanism inside coin B must be a wave.\nCoin A can also be put such that it is not quite in line with coin B but still touching B.\nAlso then momentum transfer takes place and A is launched under an angle.\n\nTip\n\nPlugins are shared in a \n\nGitHub repo\n\nInclude a plugin\n\nLook at the different plugins available in the \n\nmyst-plugins GitHub repo.\nInclude one of them in your own myst.yml file and use it in a page of your book.\nRebuild the book and look at your changes.","type":"content","url":"/a-plugins","position":1},{"hierarchy":{"lvl1":"Build online with GitHub"},"type":"lvl1","url":"/workflows","position":0},{"hierarchy":{"lvl1":"Build online with GitHub"},"content":"Updated: 03 Nov 2025\n\nYou may be familiar with GitHub Actions: it is a widely used continuous integration tool which can easily and automatically publish your Jupyter Book as a website. This lesson is designed to get you familiar with GitHub Actions in your Jupyter Book and learn how to manipulate them.\n\nTip 🌶\n\nThe workflow file generated by jupyter-book init --gh-pages by 🌶 users is different than that generated by this template, but you can still follow the exercises.\n\nWhat is GitHub Actions?\n\nIf you have no idea, or are confused what an Action is, don’t despair! The most simple explanation is that GHA is a tool for automating workflows.\nFor our purposes, everything you need to know is described in this dropdown tip.\n\n“GitHub Actions” is GitHub’s product name for its Continuous Integration / Continuous Deployment (CI/CD) services: if this term is unfamiliar, it’s not important, as you can simply think of CI/CD and GH Actions as an algorithm that can be carried out on your GitHub repository automatically.\nIt is the “workflow automation” framework that sometimes seem like magic to the outside observer.\n\nWithin GHA, “workflows” are defined using .yml files in the .github/workflows folder of a repository.\nEach workflow can be triggered by one or more events, for example, a commit is pushed to the repository.\nEach workflows can have multiple steps (e.g. install software, build the book, deploy the book), and as many steps are repeated, it is possible to find pre-built “actions” in an online \n\nmarketplace.\nIn addition, workflows can include arbitrary code (e.g., bash or Python scripts).\n\nGHA is generally free for public repositories, with some limitations on usage for private repositories.\n\nBy the end of this workshop you will read and modify workflow files to customize the build and deployment of your Jupyter Book.","type":"content","url":"/workflows","position":1},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Read it"},"type":"lvl2","url":"/workflows#read-it","position":2},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Read it"},"content":"In your folder of the repository there is a hidden folder called .github, and inside that is another folder called workflows.\nInside that folder is a file called deploy.yml (or similar).\nThis file defines the workflow that builds and deploys your Jupyter Book to GitHub Pages.\n\nExplore the workflow file\n\nFind the workflow file and open it to see what is inside. See if you can answer the following questions:\n\nWhat version of Python is being used?\n\nWhat type of virtual environment is created, and how?\n\nWhat command is used to build the book?\n\nCan you see where the HTML build files are uploaded as an artifact and deployed to a GitHub Pages server?\n\ndo not change anything yet!\n\nChanging the workflow file before you understand it may break your book build! Luckily, you can always revert changes using git.","type":"content","url":"/workflows#read-it","position":3},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Observe it"},"type":"lvl2","url":"/workflows#observe-it","position":4},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Observe it"},"content":"Now that you have seen the “steps” of the workflow, it is good to see them “in action” in the Browser.\n\nWatch the workflow execute\n\nMake a commit and push it to your repository. Then visit the “Actions” tab and watch the workflow execute. Specifically, note:\n\nthe green, yellow or red “dot” indicating status of the workflow,\n\nwhen you click on the most recent workflow run, you will see a summary of the job,\n\nafter clicking on the “box” in the workflow diagram, you can see all of the workflow steps,\n\nyou can investigate each step to see the command line output.\n\nUnderstanding where this information is available in your repository is especially useful when debugging problems with your website and PDF build.\nIt is also important to know that this is where you can search for error logs (in the CLI), especially when problems may not occur in your local setup, but your website is not deploying properly.","type":"content","url":"/workflows#observe-it","position":5},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Break it"},"type":"lvl2","url":"/workflows#break-it","position":6},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Break it"},"content":"To make sure you know what a “problem” looks like, we can intentionally break the workflow.\n\nForce an error in the workflow\n\nIntroduce an error in the workflow and watch the Actions and workflow pages to observe what it looks like when an error occurs.\n\nThere are many ways to accomplish this; perhaps the easiest would be to modify the terminal commands in one of the workflow steps (e.g., replace jupyter book build with jupyter book break, which does not exist).\n\nRevert the error afterwards.","type":"content","url":"/workflows#break-it","position":7},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Change it"},"type":"lvl2","url":"/workflows#change-it","position":8},{"hierarchy":{"lvl1":"Build online with GitHub","lvl2":"Change it"},"content":"Here we will modify the workflow to add a new feature: automatically updating the “last edited” date in our published book.\n\nThe following bash script will modify date: field in the myst.yml file:- name: Add current date to myst.yml\n  shell: bash\n  run: |\n      BUILD_DATE=\"$(date +'%Y-%m-%d')\"\n      sed -i \"s|\\${BUILD_DATE}|${BUILD_DATE}|g\" myst.yml\n      echo \"myst.yml:\"\n      grep -nE '^\\s*date:' myst.yml\n\nIn addition, this simple script requires setting ${BUILD_DATE} for the date field value in myst.yml.\n\nModify the workflow file\n\nModify deploy.yml to implement the feature.\n\nConfirm this was done successfully by checking the rendered website online.\n\nTest your understanding\n\nAlthough the time is not displayed in our update, what is the actual date and time that is represented in the value BUILD_DATE?\n\nA. time that file was editedB. time of commitC. time of pushD. other\n\nCheck your answer\n\nThe answer is D, other. The time represented by BUILD_DATE corresponds to the moment when the first line in the code snippet added to the workflow file was executed in the cloud. It is closest to the time of the push, plus the extra time needed to set up the virtual environment and start the book build process.","type":"content","url":"/workflows#change-it","position":9},{"hierarchy":{"lvl1":"Create PDF output 🌶"},"type":"lvl1","url":"/pdfoverview","position":0},{"hierarchy":{"lvl1":"Create PDF output 🌶"},"content":"Updated: 03 Nov 2025\n\nJupyter Book is centered around creating interactive online documents. However, there are several instances when a PDF, next to the online book, is desired, for example:\n\nfor use in note taking applications (e.g., students annotating a textbook chapter, or reviewing the draft of a website),\n\nif a printed copy of the book is required,\n\nto more easily carry out a plagiarism check.\n\nOne of the strengths of Jupyter Book 2 is the ease with which high-quality PDF’s can be created from the same source files as an online book. To accomplish this, a template is used to create a PDF with a consistent look and feel between the two document formats. In addition, such templates can be customized to fit the specific needs of the documents being created.\n\nThis lesson provides an overview the PDF output capabilities of the Jupyter Book 2 and MyST ecosystem, accompanied by exercises to get you started creating your own PDF output (with Typst) using two different templates. The following pages:\n\nintroduce document generation with MyST (including an explanation of templates),\n\npresent an overview and comparison of PDF generation with Typst and LaTeX, and\n\nprovide exercises to generate a PDF with a Typst template, both locally and using GitHub Actions.","type":"content","url":"/pdfoverview","position":1},{"hierarchy":{"lvl1":"MyST Document Creation 🌶"},"type":"lvl1","url":"/a-myst","position":0},{"hierarchy":{"lvl1":"MyST Document Creation 🌶"},"content":"Updated: 02 Nov 2025\n\nThis page introduces a few key concepts that will help understand how Jupyter Book 2 creates documents from source files written using MyST Markdown. We are particularly interested in understanding how themes and templates are used to create a website and PDF, respectively.\n\nOnly a very brief overview is provided here; for additional technical explanation, refer to the \n\nstack overview section of the MyST Guide, as well as the \n\nSciPy Paper.\n\nTip\n\nThe term “MyST” is used here, rather than “Jupyter Book”, because MyST is the underlying technology that Jupyter Book 2 uses to create documents. \n\nAs described elsewhere:\n\nJupyter Book 2 is a lightweight distribution and configuration layer on top of these and other components of the MyST ecosystem. It is meant to provide an opinionated experience of MyST–for example, by turning on certain features by default...","type":"content","url":"/a-myst","position":1},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"Key MyST Components"},"type":"lvl2","url":"/a-myst#key-myst-components","position":2},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"Key MyST Components"},"content":"As you already know, Jupyter Book 2 is able to convert MyST Markdown written *.md and *.ipynb source files into websites: online books. However, there are many other formats that MyST can convert to, including PDF, LaTeX, Word, JATS XML, and more. The process is illustrated in the following figure:\n\n\n\nDocuments made in MyST Markdown can be converted to many different formats. These can be saved as JSON, or rendered to a website (like this one!) or any number of formats including \n\nPDF & LaTeX, \n\nWord, \n\nReact, or \n\nJATS. Picture taken from the MYST documentation .\n\nIn the demonstration below below, each tab illustrates the various output formats for a given MyST Markdown input:","type":"content","url":"/a-myst#key-myst-components","position":3},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"MyST Build Process"},"type":"lvl2","url":"/a-myst#myst-build-process","position":4},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"MyST Build Process"},"content":"The “build” process, the process of converting MyST Markdown into a given output format, is more complex than the figure above suggests. In fact, it has \n\n5 key steps: writing, parsing, resolving, rendering and exporting. Of this process, illustrated below, only the final step is of interest to us here, as it is where the rendered components of a document are combined with a theme (for websites) or a template (for PDF’s) to create the final output document.\n\n\n\nHigh-level overview of Jupyter Book 2 components. Picture taken from Figure 1 of the Scipy paper .","type":"content","url":"/a-myst#myst-build-process","position":5},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"Themes and Templates"},"type":"lvl2","url":"/a-myst#themes-and-templates","position":6},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"Themes and Templates"},"content":"For our purposes, a theme or template defines the final appearance of our document. Though a concise explanation is provided \n\nhere, for this workshop it is sufficient to know that there are a number of different themes and templates available in the MyST ecosystem, and that it is possible to customize them to a high degree. An overview is provided at the \n\nmyst-templates GitHub organization.\n\nNote in particular that there are currently only two themes in this organization: book-theme and article-theme. These are the \n\ntwo themes bundled with MyST and correspond to the two types of websites that can be created. The code snippet below is from the myst.yml file of this book, which indicates the book-theme is used:\n\nsite:\n  template: book-theme\n  options:\n    favicon: ./content/figures/favicon.svg      # path to your favicon\n    style: ./style/custom.css\n    logo: ./content/figures/logo.svg            # path to your logo, shown top left at site\n    folders: false\n    hide_authors: true\n\nProgram 1:Example of the book-theme specified in the myst.yml file.\n\nThere is a relatively large number of templates listed in the \n\nmyst-templates GitHub organization, the vast majority of which create LaTeX documents (i.e., *.tex files). In fact, many of these templates are for articles formatted for publishing with specific journals and are used in combination with websites created using the article-theme to generate a PDF. The code snippet below is from the myst.yml file of this book, which indicates the book-theme is used:\n\n  exports:\n    - format: typst\n      template: lapreprint-typst\n      output: exports/book.pdf\n      id: output-pdf\n\nProgram 2:Example of the book-theme specified in the myst.yml file.","type":"content","url":"/a-myst#themes-and-templates","position":7},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"Summary"},"type":"lvl2","url":"/a-myst#summary","position":8},{"hierarchy":{"lvl1":"MyST Document Creation 🌶","lvl2":"Summary"},"content":"That’s enough detail about the MyST ecosystem for now. The main takeaways from this page are to recognize:\n\nthemes and templates are used to customize the creation of final documents for a given source\n\nthis book is initially set up with the book-theme for website generation and the lapreprint-typst template for PDF generation\n\nUp to this point in the workshop you have been modifying the source code and using the book-theme to view changes on the rendered website; however, you have not yet generated a PDF. After a quick introduction to LaTeX and Typst on the following page, we will do just that in the next round of exercises!\n\nhttps://​mystmd​.org​/guide/\n\nhttps://​proceedings​.scipy​.org​/articles​/hwcj9957​#overview​-of​-jupyter​-book​-2s​-architecture","type":"content","url":"/a-myst#summary","position":9},{"hierarchy":{"lvl1":"PDFs with Typst and LaTeX 🌶"},"type":"lvl1","url":"/b-pdfgeneration","position":0},{"hierarchy":{"lvl1":"PDFs with Typst and LaTeX 🌶"},"content":"Updated: 02 Nov 2025\n\nJupyter Book 2 currently supports two primary ways to export your book as a PDF: LaTeX or Typst.\nBoth are powerful tools for generating high-quality PDFs, but they differ in several key aspects (additional advantages and disadvantages \n\ndescribed here):\n\nFeature\n\nTypst\n\nLaTeX\n\nEase of Use\n\nModern syntax, easier to learn and use\n\nSteeper learning curve, more complex syntax\n\nSpeed\n\nFast compilation\n\nSlower compilation, especially for large docs\n\nCustomization\n\nTemplates are easy to modify\n\nHighly customizable, but requires more effort\n\nIntegration\n\nDesigned for MyST Markdown and Jupyter Book\n\nWidely supported in academic publishing\n\nCommunity\n\nGrowing, newer ecosystem\n\nLarge, established community\n\nFeatures\n\nGood support for math, figures, and tables\n\nExtensive support for math, figures, tables, and packages\n\nOutput Quality\n\nHigh-quality, modern look\n\nProfessional, traditional academic look\n\nIn short: choose Typst for simplicity and speed, or LaTeX for advanced customization and compatibility with academic standards.\n\nBelow we provide the screen shots of the PDF output using Typst (left) using the \n\nplain​_typst​_template and LaTeX (right) using the \n\nplain​_latex​_template.\n\n\n\nFigure 1:Comparison of PDF output using Typst (left) and LaTeX (right) using both the plain book template.\n\nYou can specify the \n\noutput template, download the template and tweak to match your preferences.\nWe won’t go into detail here, but you can find more information \n\nin the MyST Markdown documentations.\n\nNote\n\nOne reason Typst is preferred in this workshop is that the installation (both for local users and via GitHub Actions) is much faster and easier than LaTeX, as you will see when we implement the PDF generation in our workflow file.","type":"content","url":"/b-pdfgeneration","position":1},{"hierarchy":{"lvl1":"PDFs with Typst and LaTeX 🌶","lvl2":"Interactive file types"},"type":"lvl2","url":"/b-pdfgeneration#interactive-file-types","position":2},{"hierarchy":{"lvl1":"PDFs with Typst and LaTeX 🌶","lvl2":"Interactive file types"},"content":"When starting your own project, consider whether a PDF output is desired.\nIf so, consider the interactive elements that may be included and that some functionality and multimedia types are not supported in a PDF.\nFor instance, a *.gif file or movie cannot be included in a PDF.\nJB2 is thoughtful in this by choosing the best possible alternative if multiple files with the same name but different extensions are present: gif is chosen over png, png over jpg.\n\nTip\n\nWhen incorporating interactive media files with an alternative “static” file extension, rather than specifying the filename with extension, you can just use the file name and an asterisk, e.g. ![figure](figures/mystvstex.*). Then Jupyter Book 2 will include the proper file type depending on the export format being used.\n\nFor YouTube clips and online interactive materials embedded through iframes, you can make use of plugins.\nSee for instance the \n\niframe-to-thumbnail plugin.\nThis plugin replaces the iframe with a thumbnail image that links to the original content as well as a QR code and a link in the caption.","type":"content","url":"/b-pdfgeneration#interactive-file-types","position":3},{"hierarchy":{"lvl1":"Create a PDF 🌶"},"type":"lvl1","url":"/c-pdfoutput","position":0},{"hierarchy":{"lvl1":"Create a PDF 🌶"},"content":"Updated: 03 Nov 2025\n\nWith a general understanding of document creation using MyST and our choice to use Typst for PDF generation, you are ready to create a PDF from your book repository using Jupyter Book.\n\nIn this lesson, we will:\n\nInstall Typst (or use it within a GitHub Action workflow if working online-only)\n\nGenerate a PDF using the lapreprint-typst template\n\nSet up and use the plain_typst_book template\n\nModify the GitHub Action workflow to generate a PDF\n\nExplore how the PDF can be customized and shared via the book website\n\nWarning\n\nTo complete this lesson locally, you will need to install Typst. If this is not possible, or you are following the online-only path, you can complete the exercises using GitHub Actions. As before, the exercises in this lesson use Locally and Online to distinguish instructions for each case.\n\nThis lesson also uses GitHub Actions for both local and online approaches. If you struggle with some of the GHA exercises below, refer to \n\nthe previous lesson.","type":"content","url":"/c-pdfoutput","position":1},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"Install Typst"},"type":"lvl2","url":"/c-pdfoutput#install-typst","position":2},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"Install Typst"},"content":"To produce a PDF output locally, you need to have Typst installed on your system.\n\nInstall Typst\n\nInstall Typst using the nstructions available at the \n\nTypst GitHub repo and Jupyter Book 2 context is provided \n\nhere.\n\nCheck whether Typst is correctly installed by running the following command in your terminal:typst --version\n\nUntil you get to the Lesson “PDF output with GH Actions” you won’t be generating PDF’s, but you can still follow the exercise to learn how the template is defined and used in your Jupyter Book.","type":"content","url":"/c-pdfoutput#install-typst","position":3},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"Generate a PDF"},"type":"lvl2","url":"/c-pdfoutput#generate-a-pdf","position":4},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"Generate a PDF"},"content":"Once Typst is installed and available in your terminal it can be used with Jupyter Book to generate a PDF file.\n\nGenerate a PDF of your book\n\nGenerate a PDF using the command jupyter book build --pdf.\n\nView the PDF and observe how the contents of your website are formatted in the PDF document.\n\nNext, review the contents of the myst.yml file and answer the following questions:\n\nWhat template is being used?\n\nWhere is the PDF output file saved after being generated?\n\nReview the contents of the myst.yml file and answer the following questions:\n\nWhat template is being used?\n\nWhere is the PDF output file saved after being generated?\n\nGood practice with PDFs and Git\n\nGit is not intended for use with binary files like PDF’s. When working with PDF’s locally you may be tempted to commit the generated file to your repository, especially if you intend to share your work online. However, this will lead to unnecessary large Git workspace and is not recommended. For this reason the .gitignore  file already ignores PDF files, and the upcoming exercise with GH Actions illustrates how a PDF can be generated online and saved as a downloadable artifact, rather than committing it to the repository.","type":"content","url":"/c-pdfoutput#generate-a-pdf","position":5},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"PDF output with GH Actions"},"type":"lvl2","url":"/c-pdfoutput#section-pdf-with-gha","position":6},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"PDF output with GH Actions"},"content":"Building and including your PDF is possible through a GitHub Action workflow that automatically builds the PDF when you push changes to GitHub. This has both is pros and cons. For instance, the build of your PDF is done prior to the build of your book, and if there is an error in the workflow your website may not be updated, or the PDF may not be included as a download. On the other hand, you do not need to install anything locally and the PDF is always up to date when you push changes. The most important reason for including the PDF build in your GHA workflow is that your PDF will be generated and included automatically as a downloadable file along with your website. You will learn to do this in several ways by the end of this lesson.\n\nThe workflow steps are:jobs:\n  deploy:\n    ...\n    steps:\n      ...\n      - uses: typst-community/setup-typst@v4\n      ...\n    - name: Build PDF\n      run: |\n        jupyter book build --pdf\n\n    - name: Upload Output PDF as Artifact\n      uses: actions/upload-artifact@v4\n      with:\n        name: Output PDF\n        path: exports/book.pdf\n        compression-level: 0\n\nChange the workflow\n\nUsing the example code provided above, update your deploy.yml file to build the PDF as part of your GitHub Action workflow.\n\nVisit the Actions page of your repository to find where the artifact (PDF) can be downloaded.\n\nHint\n\nClick on the last completed workflow run and look to the bottom of the page.\n\nUsing the example code provided above, update your deploy.yml file to build the PDF as part of your GitHub Action workflow.\n\nVisit the Actions page of your repository to find where the artifact (PDF) can be downloaded.\n\nHint\n\nClick on the last completed workflow run and look to the bottom of the page.","type":"content","url":"/c-pdfoutput#section-pdf-with-gha","position":7},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"Change the PDF template"},"type":"lvl2","url":"/c-pdfoutput#change-the-pdf-template","position":8},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"Change the PDF template"},"content":"Take a look at the PDF generated in the previous exercises using the lapreprint-typst template. You probably notice that it is does a good job at converting the website into a PDF document. However, you may have also noticed some text or formatting that isn’t perfect, or perhaps you thought that you might want a cover page or table of contents for the PDF.\n\nIt turns out the lapreprint-typst template is not ideal for rendering content designed as a website made with the book-theme. Luckily, another Typst template is available: \n\nthe Plain Typst Book plain_typst_book (not yet listed on the MyST Templates GH Organization). An example YAML snippet that implements this in the myst.yml file is illustrated here:  exports:\n    - format: typst\n      template: https://github.com/myst-templates/plain_typst_book.git\n      output: exports/book.pdf\n      id: output-pdf\n\nChange the template\n\nUsing the example code provided above, update your myst.yml file to use the plain_typst_book template in your book, then rebuild the PDF.\n\nObserve how the rendered PDF is different than the previous template.\n\nUsing the example code provided above, update your myst.yml file to use the plain_typst_book template in your book. After making a commit, wait for the workflow run to complete, then view the PDF after downloading it as an artifact.\n\nObserve how the rendered PDF is different than the previous template.","type":"content","url":"/c-pdfoutput#change-the-pdf-template","position":9},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"More fun with PDF’s"},"type":"lvl2","url":"/c-pdfoutput#more-fun-with-pdfs","position":10},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl2":"More fun with PDF’s"},"content":"Now that you have successfully created a PDF and changed the template, a few small exercises are provided here to illustrate how the template can be customized, as well as how the PDF can be included as a download via the website.\n\nYou can complete the exercises in this section in any order.","type":"content","url":"/c-pdfoutput#more-fun-with-pdfs","position":11},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl3":"Customize the PDF output","lvl2":"More fun with PDF’s"},"type":"lvl3","url":"/c-pdfoutput#customize-the-pdf-output","position":12},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl3":"Customize the PDF output","lvl2":"More fun with PDF’s"},"content":"The plain_typst_book template includes options that can be set by the user to customize how the PDF is generated. For example, cover, logo logo_width and ToC_depth are added to the myst.yml file.  exports:\n    - format: typst\n      template: https://github.com/myst-templates/plain_typst_book.git\n      output: exports/book.pdf\n      id: output-pdf\n      cover: content/figures/logo.svg\n      logo: content/figures/logo.svg\n      logo_width: 5\n      ToC_depth: 2\n\nAdd template options\n\nUsing the example code provided above, update your myst.yml file to customize the PDF output, then rebuild the PDF. Feel free to experiment with the images and parameters.\n\nUsing the example code provided above, update your myst.yml file to customize the PDF output. Feel free to experiment with the images and parameters.\n\nMake a commit and download the artifact to view the change.","type":"content","url":"/c-pdfoutput#customize-the-pdf-output","position":13},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl3":"Add Download PDF button to website","lvl2":"More fun with PDF’s"},"type":"lvl3","url":"/c-pdfoutput#add-download-pdf-button-to-website","position":14},{"hierarchy":{"lvl1":"Create a PDF 🌶","lvl3":"Add Download PDF button to website","lvl2":"More fun with PDF’s"},"content":"You may have noticed a large “Feedback” button at the top right of your website. This is one example of what Jupyter Book 2 (and MyST) refer to as “actions” (not the same as GitHub Actions!). It would be very useful to include a similar button for downloading the PDF of your book. This can be done by adding the following values to the actions sub-section of the site section in myst.yml:site:\n  ...\n  actions:\n      ...\n      - title: PDF\n        url: ./exports/book.pdf\n\nAdd PDF Download button\n\nUsing the example code provided above, add a PDF download button. Once the myst.yml file has been updated the PDF must be regenerated and the website updated.\n\nConfirm that this was done successfully by checking that the PDF button downloads the file properly.\n\nUsing the example code provided above, add a PDF download button. Once the myst.yml file has been updated the PDF must be regenerated and the website updated, which is done automatically once the commit is made.\n\nConfirm that this was done successfully by checking that the PDF button downloads the file properly.\n\nOrder matters!\n\nNote that in order for the PDF to be included in the website, the PDF must be generated before the website is built. When working locally, this means you need to run the build command before updating the website. For GitHub Actions, the PDF build step must be listed above the HTML build step.","type":"content","url":"/c-pdfoutput#add-download-pdf-button-to-website","position":15},{"hierarchy":{"lvl1":"Empty book"},"type":"lvl1","url":"/init","position":0},{"hierarchy":{"lvl1":"Empty book"},"content":"Updated: 30 Oct 2025\n\nWell done!\nYou have completed the Jupyter Book workshop.\nNow you have completed this tutorial, it is time to create a book from scratch.\nIf you haven’t done so already, it is first time to install the required \n\nsoftware.\nIf done so, follow the instructions in the \n\nadvanced start.\n\nWhen running the command jupyter-book init, a book will be automatically created where all markdown and jupyter notebook files at that location will be included (in alphabetical order).","type":"content","url":"/init","position":1},{"hierarchy":{"lvl1":"Executable content introduction"},"type":"lvl1","url":"/executable","position":0},{"hierarchy":{"lvl1":"Executable content introduction"},"content":"Updated: 03 Nov 2025\n\nMyST supports a number of ways to include executable content in your project.\n\nTip\n\nInstructions are provided here for Jupyter Lab, however, you can use any IDE you are comfortable with. An explanation is provided on the \n\nSoftware page.","type":"content","url":"/executable","position":1},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Installing Jupyter"},"type":"lvl2","url":"/executable#installing-jupyter","position":2},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Installing Jupyter"},"content":"Executable content in MyST is processed by a \n\nJupyter server and appropriate \n\nkernel.\nIn this lesson, we will run a local Jupyter server to execute code cells.\n\nA pip requirements file, requirements.txt in the root of the repository specifies all of the dependencies you need.\nYou can install all of these in a virtual environment using pip and then launch Jupyter.\n\npython3 -m venv ./venv\nsource ./venv/bin/activate\npip install -r requirements.txt\njupyter lab\n\npython -m venv venv\n\nFor Command Promptvenv\\Scripts\\activate.bat\n\nFor PowerShellvenv\\Scripts\\activate.ps1\n\nThenpip install -r requirements.txt\njupyter lab\n\nThis will automatically open the Jupyter Lab interface (at \n\nlocalhost:8888) in your browser, which we will use later.\n\nUsing GitHub actions\n\nOne can use GitHub Actions to execute content at build time on GitHub servers as well, see an example deploy.yml \n\nbelow. More on the GitHub actions in the next lesson.","type":"content","url":"/executable#installing-jupyter","position":3},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Options"},"type":"lvl2","url":"/executable#options","position":4},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Options"},"content":"","type":"content","url":"/executable#options","position":5},{"hierarchy":{"lvl1":"Executable content introduction","lvl3":"Jupyter Notebook outputs","lvl2":"Options"},"type":"lvl3","url":"/executable#jupyter-notebook-outputs","position":6},{"hierarchy":{"lvl1":"Executable content introduction","lvl3":"Jupyter Notebook outputs","lvl2":"Options"},"content":"MyST can use Jupyter notebooks, .ipynb files, as input just like Markdown.\nIf you have a notebook which you have executed, you can add it to the book.\nMarkdown cells will be rendered in exactly the same way as a Markdown file.\nSo you can use all of the MyST Markdown you have already learned.\nOutputs such as images and interactive plots will also be rendered in the book.\n\nBlocks can be labelled, either by editing a cell’s JSON metadata, or with the following syntax,#| label: my-label\n\nLabels are particularly useful when integrating notebooks into larger documents such as theses or technical reports. By assigning labels to code blocks, and their corresponding outputs, you can reference them directly within your text, making it clear which code produced which figure, table, or result. \n\nThis example makes use of labels to reference figures from the Python notebook.\n\nNote\n\nThis is the syntax for Python, where # is the comment character.\nFor other languages, the syntax is the comment character followed by |.\nIn Javascript, for example, the above label would be,//| label: my-label\n\nFigures can be given a caption in a similar way,#| caption: Caption text\n\nWe will explore using Jupyter notebooks as input for MyST in \n\nAdding a Jupyter Notebook.","type":"content","url":"/executable#jupyter-notebook-outputs","position":7},{"hierarchy":{"lvl1":"Executable content introduction","lvl3":"Executing at build time","lvl2":"Options"},"type":"lvl3","url":"/executable#executing-at-build-time","position":8},{"hierarchy":{"lvl1":"Executable content introduction","lvl3":"Executing at build time","lvl2":"Options"},"content":"MyST can also execute content at build time, through connecting to a Jupyter server.\nExecutable cells can be in the .ipynb format as well as written in Markdown using either the \n\ncode-cell directive or \n\neval role.\n\nWe will cover executing at build time with Jupyter Notebooks in \n\nAdding a Jupyter Notebook, and with Markdown in \n\nExecutable Markdown.","type":"content","url":"/executable#executing-at-build-time","position":9},{"hierarchy":{"lvl1":"Executable content introduction","lvl3":"In page execution","lvl2":"Options"},"type":"lvl3","url":"/executable#in-page-execution","position":10},{"hierarchy":{"lvl1":"Executable content introduction","lvl3":"In page execution","lvl2":"Options"},"content":"Through connecting your site to a remote Jupyter, it is also possible to execute code cells live, in the browser.\nThis feature is excellent for presenting readers with interactive elements, such as data science workflows they can follow along, or exercises where they are invited to change code.\n\nIn page execution is not covered in this lesson.","type":"content","url":"/executable#in-page-execution","position":11},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Adding a Jupyter Notebook"},"type":"lvl2","url":"/executable#lesson-exec-jupyternb","position":12},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Adding a Jupyter Notebook"},"content":"In this repository we have included a Jupyter notebook, example.ipynb, which has been executed and includes outputs.\n\nAdd a .ipynb file to the book\n\nAdd the example notebook to the book by giving it an entry in the table of contents in myst.yml.\nRebuild the book and look at the new page.\n\nMake changes\n\nNavigate to \n\nyour Jupyter Lab instance.\nMake some changes to the notebook.\nTry adding,\n\nMarkdown cells\n\nCode cells in Python\n\nRerun the entire notebook by clicking “Run” -> “Restart Kernel and Run All Cells…”\nRebuild the book and look at your changes.\n\nExecute at build time\n\nInstead of running the notebook in Jupyter Lab, you can also execute the notebook as the book is built.\nTo do this, run,myst start --execute\n\nHint\n\nIf you installed Jupyter in a virtual environment, like we recommended above, you will need to run myst in that environment so that a Jupyter server can be launched.source ./venv/bin/activate\nmyst start --execute\n\nNow, make changes to the notebook and save it without running the cells.\nYou will see MyST detect the notebook has been changed and re-run it automatically.","type":"content","url":"/executable#lesson-exec-jupyternb","position":13},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Executable Markdown"},"type":"lvl2","url":"/executable#lesson-exec-markdown","position":14},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Executable Markdown"},"content":"Unlike Jupyter notebook files, Markdown files do not store the output of executions.\nThis means to include the outputs in our project, we must execute the cells at build time.\nTo make a Markdown file executable, you must first add a kernelspec to the files \n\nfrontmatter.\nFor example, in this page,---\nkernelspec:\n    name: python3\n    display_name: 'Python 3'\n---\n\nTip\n\nThe MyST Guide has a section on \n\nthe advantages of the .md and .ipynb formats.\n\nYou can add a block of executable code using the \n\ncode-cell directive.\nThe directive has the format,:::{code-cell} <language>\n:key: value\n<code>\n:::\n\nThe key/value pairs allow you to tag the cell in the same way as \n\nwith ipynb.\n\nCode cells\n\nNote\n\nWe will use the default Python kernel in these examples.\nHowever, you can use another kernel, such as Javascript, R or Julia \n\nby changing the page frontmatter and updating code cell blocks.\n\nPut the following Python snippet in a code cell.def fib(n):\n    if n < 0:\n        return\n    if n in [0, 1]:\n        return n\n    else:\n        return fib(n-2) + fib(n-1)\n\n\nfor i in range(10):\n    print(i, fib(i))\n\nRebuild the book (with the --execute flag) and look at the result.\n\nNow, add a label (using the key/value notation) to the code cell and reference it \n\nhere.\nMake the code cell a figure by adding a caption; notice how the reference changes.\n\nYou can also use the \n\neval role to execute expressions in Markdown text.\n\nInline execution\n\nCopy the following examples using the eval role and complete the statements to execute.$6872 \\times 3409$ is {eval}``\n\nThe first 15 multiples of 23 are {eval}``\n\nHint\n\nFor the second example, you may want to use a \n\nlist comprehension.","type":"content","url":"/executable#lesson-exec-markdown","position":15},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Cell Tags and Hiding Input"},"type":"lvl2","url":"/executable#cell-tags-and-hiding-input","position":16},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"Cell Tags and Hiding Input"},"content":"Cell tags in Jupyter Notebooks are metadata labels that you can assign to individual cells.\nThey are useful for customizing the behavior of cells, such as hiding code input.\nMarkdown cells allow you to add tags as well, e.g. :tags: [hide-input].\n\nTo hide the input of a code cell (so only the output is visible), you can add a tag like hide_input to that cell.\nJB2 recognizes this tag and will hide the code input when rendering or exporting the notebook.\n\nTo add a tag:\n\nSelect the cell.\n\nOpen the “View” menu and enable the “Cell Toolbar” → “Tags”.\n\nAdd the tag hide_input (or another tag recognized by your toolchain).\n\nThis feature is especially useful for creating clean, reader-friendly notebooks where you want to focus on results rather than code details, see below.\n\nprint(\"This is the output of the cell, but the input code is hidden.\")\n\n\n\nRemove input\n\nCreate a code cell that calculates the square of numbers from 5 to 8 and prints the results.\nRemove the input code from being displayed by adding the appropriate tag.","type":"content","url":"/executable#cell-tags-and-hiding-input","position":17},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"GitHub Actions Example"},"type":"lvl2","url":"/executable#gha-example","position":18},{"hierarchy":{"lvl1":"Executable content introduction","lvl2":"GitHub Actions Example"},"content":"Here is an example GitHub Action workflow file to illustrate one possible way to build a virtual environment and execute notebooks during the book build. We will cover other aspects of the workflow file in later lessons (for example, GH Actions itself and PDF generation).\n\nGitHub Action workflow examplename: MyST GitHub Pages Deploy\non:\n  push:\n    branches: [main]\nenv:\n  # `BASE_URL` determines the website is served from, including CSS & JS assets\n  # You may need to change this to `BASE_URL: ''`\n  BASE_URL: /${{ github.event.repository.name }}\n\n# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages\npermissions:\n  contents: read\n  pages: write\n  id-token: write\n\nconcurrency:\n  group: 'pages'\n  cancel-in-progress: false\njobs:\n  deploy:\n    environment:\n      name: github-pages\n      url: ${{ steps.deployment.outputs.page_url }}\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: Setup Pages\n        uses: actions/configure-pages@v3\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 18.x\n      - uses: typst-community/setup-typst@v4\n\n    # Install Python and dependencies\n      - name: Set up Python\n        uses: actions/setup-python@v5\n        with:\n          python-version: '3.11'   # or your version\n\n      - name: Install Python dependencies\n        run: |\n          python -m pip install --upgrade pip\n          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi\n          pip install jupyter-server nbclient nbformat ipykernel jupyter-client\n          # pip install plotly kaleido          \n          python -m ipykernel install --user --name=python3\n          \n    # Install MyST \n      - name: Install MyST Markdown\n        run: npm install -g mystmd\n      \n    # Build PDF\n      - name: Build PDF\n        run: |\n          myst build --pdf\n\n      - name: Upload Output PDF as Artifact\n        uses: actions/upload-artifact@v4\n        with:\n          name: Output PDF\n          path: exports/book.pdf\n          compression-level: 0\n    \n          # Build book\n      - name: Build execute \n        run: myst build --execute --html\n\n      - name: Upload artifact\n        uses: actions/upload-pages-artifact@v3\n        with:\n          path: './_build/html'\n          \n      - name: Deploy to GitHub Pages\n        id: deployment\n        uses: actions/deploy-pages@v4","type":"content","url":"/executable#gha-example","position":19},{"hierarchy":{"lvl1":"Reusing and sharing content"},"type":"lvl1","url":"/reuse","position":0},{"hierarchy":{"lvl1":"Reusing and sharing content"},"content":"Updated: 02 Nov 2025\n\nMyST has strong support for referencing and reusing content.\nMyST nodes can be referenced or embedded, even from external projects!\nThese features help to more seamlessly share content between MyST projects, so your project can become part of a larger network of resources.","type":"content","url":"/reuse","position":1},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl2":"Referencing"},"type":"lvl2","url":"/reuse#referencing","position":2},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl2":"Referencing"},"content":"","type":"content","url":"/reuse#referencing","position":3},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"Internally","lvl2":"Referencing"},"type":"lvl3","url":"/reuse#internally","position":4},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"Internally","lvl2":"Referencing"},"content":"Review the \n\nreferences section of the cheat sheet for a reminder of the syntax.\n\nGlobal labels\n\nThe labels you give MyST nodes are “global”.\nYou can refer to them in any part of your project, not just on the page where you defined them.\n\nReference the equation with label eq_newton from the cheat sheet \n\nhere.\n\nLabel anything\n\nAdd a label to this paragraph.\n\nAnd reference it \n\nhere.","type":"content","url":"/reuse#internally","position":5},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"External MyST projects","lvl2":"Referencing"},"type":"lvl3","url":"/reuse#external-myst-projects","position":6},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"External MyST projects","lvl2":"Referencing"},"content":"The \n\nMyST guide has already been added as an external reference for this project.\nIt has been given the label myst-guide, so it can be referenced with [](xref:myst-guide).\n\n  references:\n    myst-guide: https://mystmd.org/guide\n\nReference the MyST guide\n\nCreate a reference to an object in the MyST guide.\nTry referencing some different types of node, like pages, sections, paragraphs, figures and so on.\n\nAdd a new external reference\n\nEdit myst.yml and add The Turing Way (\n\nhttps://​book​.the​-turing​-way​.org) as an external reference in the references block.\n\nUse the label you gave The Turing Way to create a reference.","type":"content","url":"/reuse#external-myst-projects","position":7},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl2":"Embedding"},"type":"lvl2","url":"/reuse#embedding","position":8},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl2":"Embedding"},"content":"The \n\nembed directive allows you to reuse content in-place.\nThis is helpful if you want to have the same content in two places, without repeating the source or interrupting the flow of a page with a link.","type":"content","url":"/reuse#embedding","position":9},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"Internally","lvl2":"Embedding"},"type":"lvl3","url":"/reuse#internally-1","position":10},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"Internally","lvl2":"Embedding"},"content":"Embed the table tl_basic_formatting from the cheat sheet using the embed directive syntax:::{embed} label\n:::","type":"content","url":"/reuse#internally-1","position":11},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"External MyST projects","lvl2":"Embedding"},"type":"lvl3","url":"/reuse#external-myst-projects-1","position":12},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"External MyST projects","lvl2":"Embedding"},"content":"Just like with cross-references, you can also embed content from external MyST projects.\n\nEmbed the figure sunset-figure from the \n\nMyST guide\n\nHint\n\nRemember that to reference an external MyST project you use xref: and the label given to the project in myst.yml.\nIn this case that is xref:myst-guide.","type":"content","url":"/reuse#external-myst-projects-1","position":13},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl2":"Referencing other internet resources"},"type":"lvl2","url":"/reuse#referencing-other-internet-resources","position":14},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl2":"Referencing other internet resources"},"content":"Like with MyST references, some links to non-MyST resources are handled specially and have dynamic, interactive tooltips.","type":"content","url":"/reuse#referencing-other-internet-resources","position":15},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"Wikipedia","lvl2":"Referencing other internet resources"},"type":"lvl3","url":"/reuse#wikipedia","position":16},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"Wikipedia","lvl2":"Referencing other internet resources"},"content":"Reference a Wikipedia page\n\nUse [](wiki:) to create a reference to your favourite Wikipedia article.","type":"content","url":"/reuse#wikipedia","position":17},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"DOIs","lvl2":"Referencing other internet resources"},"type":"lvl3","url":"/reuse#dois","position":18},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"DOIs","lvl2":"Referencing other internet resources"},"content":"Reference a document by its DOI\n\nUse [](doi:) to create a reference to a document.\n\nHint\n\nYou can find many documents with DOIs on \n\nZenodo","type":"content","url":"/reuse#dois","position":19},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"GitHub","lvl2":"Referencing other internet resources"},"type":"lvl3","url":"/reuse#github","position":20},{"hierarchy":{"lvl1":"Reusing and sharing content","lvl3":"GitHub","lvl2":"Referencing other internet resources"},"content":"Links to GitHub have dynamic tooltips which can show issues, pull requests, and lines of code.\n\nReference items in GitHub\n\nUse [](https://github.com) to create a references to GitHub objects.\n\nHint\n\nIf you are not sure which GitHub repository to use, try \n\nmystmd.","type":"content","url":"/reuse#github","position":21},{"hierarchy":{"lvl1":"Create your first Jupyter Book 2"},"type":"lvl1","url":"/your-turn","position":0},{"hierarchy":{"lvl1":"Create your first Jupyter Book 2"},"content":"Updated: 31 Oct 2025\n\nNow it’s your turn to get going creating content in a Jupyter Book.\n\nThere are some conditions to meet before you can get started:\n\nProgramming and Git experience are not strictly necessary, but it does make things a bit easier.\n\nA free \n\nGitHub account.\n\nA little bit of patience, it’s a steep learning curve.\n\nOptional:\n\nSoftware to write your code in, such as Jupyter Lab or \n\nVisual Studio Code (VSC).\n\nTip\n\nIf you are feeling confident and would rather start building a document from scratch using the CLI on your computer, you can look at \n\nthe advanced start option 🌶.\n\nWe provide instructions for building using the GitHub development IDE, as well as building locally. For the latter we assume knowledge about VSC, and the use of git.\n\nReady? Let’s get started…","type":"content","url":"/your-turn","position":1},{"hierarchy":{"lvl1":"Software"},"type":"lvl1","url":"/software","position":0},{"hierarchy":{"lvl1":"Software"},"content":"Updated: 03 Nov 2025\n\nThis page provides an overview of commonly used software, with limited instructions for using them.","type":"content","url":"/software","position":1},{"hierarchy":{"lvl1":"Software","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl2","url":"/software#integrated-development-environment-ide","position":2},{"hierarchy":{"lvl1":"Software","lvl2":"Integrated Development Environment (IDE)"},"content":"An IDE is required to complete many of the exercises in this workshop. Many of them could be completed in a simple text editor, however, an IDE that includes features such as version control with Git, environment management and a CLI would be useful. As such, the instructions herein often refer to Jupyter Lab. However, you can choose your own IDE, noting that the main requirements are dictated by the use of Jupyeter Notebook (*.ipynb) files:\n\nability to edit notebooks natively (i.e., not editing the raw JSON),\n\naccess to a Jupyter server and Python kernel for executing notebooks.","type":"content","url":"/software#integrated-development-environment-ide","position":3},{"hierarchy":{"lvl1":"Software","lvl3":"Jupyter Lab","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl3","url":"/software#jupyter-lab","position":4},{"hierarchy":{"lvl1":"Software","lvl3":"Jupyter Lab","lvl2":"Integrated Development Environment (IDE)"},"content":"To run Jupyter Notebooks we can use IDE’s as Jupyter Notebook or Jupyter Lab. Jupyter Notebook is a web-based interface that allows users to create and share documents with live code, visualizations, and narrative text in a linear format. Jupyter Lab, on the other hand, is a more advanced interface offering a flexible and modular environment with multiple panels, including notebooks, terminals, and text editors, providing a more versatile experience for interactive computing. I prefer to use Jupyter lab.","type":"content","url":"/software#jupyter-lab","position":5},{"hierarchy":{"lvl1":"Software","lvl3":"GitHub web-based editor","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl3","url":"/software#github-web-based-editor","position":6},{"hierarchy":{"lvl1":"Software","lvl3":"GitHub web-based editor","lvl2":"Integrated Development Environment (IDE)"},"content":"The \n\ngithub.dev web editor makes it possible to edit files directly in the browser. This is an excellent option if you are unable to install software on your computer. To activate it, simply navigate to a GitHub repository and press .. It’s really that easy!\n\nTip\n\nNote that while this IDE can be used for many of the exercises in this workshop, and you can edit Jupyter Notebook files, you will not be able to use iexecute notebooks directly in the browser (however, notebooks will be executed during build in the GitHub Actions workflow).\n\nYou can find out more about this useful tool \n\nhere.","type":"content","url":"/software#github-web-based-editor","position":7},{"hierarchy":{"lvl1":"Software","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl3","url":"/software#vsc","position":8},{"hierarchy":{"lvl1":"Software","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"content":"A popular code editor is \n\nVisual Studio Code (VSC). It allows you to program in different languages, where it recognizes the commands in that language and adjusts the FONT so that it becomes better readable. Moreover, it allows you to install various packages (such as Jupyter Notebook). It also integrates GIT and allows to code using Co-Pilot, an AI pair programmer. We advise to use VSC as it allows for multiple programming languages.","type":"content","url":"/software#vsc","position":9},{"hierarchy":{"lvl1":"Software","lvl4":"Terminal","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl4","url":"/software#terminal","position":10},{"hierarchy":{"lvl1":"Software","lvl4":"Terminal","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"content":"The terminal in VSC is a tool that lets you interact with your computer’s command line directly within the editor. It’s used to run commands, scripts, or programs without leaving the coding environment. For example, you can compile code, run a development server, install dependencies, or manage files. It’s very helpful for developers because it allows you to code and execute commands in one place, streamlining your workflow.\n\n\n\nFigure 1:The VSC terminal to interact with the computer using the command line","type":"content","url":"/software#terminal","position":11},{"hierarchy":{"lvl1":"Software","lvl4":"Extensions","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl4","url":"/software#extensions","position":12},{"hierarchy":{"lvl1":"Software","lvl4":"Extensions","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"content":"Extensions in Visual Studio Code (VSC) are powerful add-ons that enhance the functionality of the editor by providing additional features, tools, and support for various programming languages, frameworks, and technologies. Extensions allow you to customize and tailor VSC to suit your specific development needs.","type":"content","url":"/software#extensions","position":13},{"hierarchy":{"lvl1":"Software","lvl5":"How to Install Extensions:","lvl4":"Extensions","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl5","url":"/software#how-to-install-extensions","position":14},{"hierarchy":{"lvl1":"Software","lvl5":"How to Install Extensions:","lvl4":"Extensions","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"content":"Access Extensions View:\n\nClick on the Extensions icon in the Activity Bar on the side (or press Ctrl+Shift+X / Cmd+Shift+X).\n\nSearch for Extensions:\n\nIn the Extensions view, you can search for the name or keywords related to the extension you want to install.\n\nInstall the Extension:\n\nClick the Install button on the desired extension, and it will automatically be added to VSC.\n\nManage Installed Extensions:\n\nYou can view, enable, disable, or uninstall extensions from the same Extensions view.","type":"content","url":"/software#how-to-install-extensions","position":15},{"hierarchy":{"lvl1":"Software","lvl5":"Popular Extensions in VSC:","lvl4":"Extensions","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"type":"lvl5","url":"/software#popular-extensions-in-vsc","position":16},{"hierarchy":{"lvl1":"Software","lvl5":"Popular Extensions in VSC:","lvl4":"Extensions","lvl3":"VSC","lvl2":"Integrated Development Environment (IDE)"},"content":"Python: Provides linting, debugging, IntelliSense, and more for Python development.\n\nJupyter: Provides support for Jupyter notebooks within VSC.\n\nArduino: Provides support for programming in Arduino.\n\nCode Spell Checker: Has a great spelling checker, also available for Dutch\n\nGithub Copilot: Your AI pair programmer. Helps you in writing code.\n\nLaTeX workshop: LaTeX coding, preview, compiling.\n\nMyST-Markdown: The official Markdown syntax extension","type":"content","url":"/software#popular-extensions-in-vsc","position":17},{"hierarchy":{"lvl1":"Software","lvl2":"Virtual Environment and Dependencies"},"type":"lvl2","url":"/software#virtual-environment-and-dependencies","position":18},{"hierarchy":{"lvl1":"Software","lvl2":"Virtual Environment and Dependencies"},"content":"It is assumed that you are able to create and activate a virtual environment in order to complete this workshop using a personal computer. As the primary tools are Python packages available using pip, the choice of environment manager is somewhat trivial. To keep things simple we suggest using Python venv or Conda.\n\nPython’s venv is used in the GitHub Actions workflows.","type":"content","url":"/software#virtual-environment-and-dependencies","position":19},{"hierarchy":{"lvl1":"Software","lvl3":"Python Dependencies","lvl2":"Virtual Environment and Dependencies"},"type":"lvl3","url":"/software#python-dependencies","position":20},{"hierarchy":{"lvl1":"Software","lvl3":"Python Dependencies","lvl2":"Virtual Environment and Dependencies"},"content":"Python dependencies are managed in file requirements.txt, the contents of which are included here:\n\njupyter-book>=2.0.0\njupyter\nmatplotlib>=3.10.7\n\n\nProgram 1:Python dependencies in file requirements.txt\n\nNote that only jupyter-book is needed for building the book as described in most of the lessons in this workshop. The remaining packages are for the executable content lesson, which requires editing and executing Jupyter Notebooks (*.ipynb files). In addition, jupyter is a metapackage that includes a number of other commonly used packages (e.g., Jupyter Lab, IPython, etc.): it is included here to cover the range of preferences and IDE’s used by workshop participants; many of these are described briefly in the table below. For each individual participant, a smaller subset of packages could be used in practice.\n\nTo install these dependencies ensure requirements.txt is in your working directory and run pip install -r requirements.txt.\n\nPackage\n\nDescription\n\njupyter-book>=2.0.0\n\nTool to build publication-quality books and documentation from Jupyter notebooks and Markdown.\n\njupyterlab\n\nWeb-based interactive development environment for notebooks, code, and data.\n\nipykernel\n\nIPython kernel for Jupyter, enables running Python code in notebooks. Necessary for VSC to edit and execute notebook files.\n\nipywidgets\n\nInteractive HTML widgets for Jupyter notebooks and JupyterLab.\n\njupyter\n\nA metapackage that requires jupyterlab, ipywidgets and ipykernel, amongst other packages.\n\nmystmd\n\nMyST Markdown support for Jupyter Book / Sphinx.\n\njupyterlab_myst\n\nJupyterLab extension to render MyST Markdown and improve notebook/Markdown integration.\n\nnumpy\n\nCore library for numerical computing with arrays and linear algebra.\n\nmatplotlib\n\n2D plotting library for generating figures and visualizations.\n\nscipy\n\nScientific computing library.","type":"content","url":"/software#python-dependencies","position":21},{"hierarchy":{"lvl1":"Software","lvl2":"PDF Generation with Typst"},"type":"lvl2","url":"/software#pdf-generation-with-typst","position":22},{"hierarchy":{"lvl1":"Software","lvl2":"PDF Generation with Typst"},"content":"For this template we use Typst to produce a high quality PDF (explained in detail as part of the PDF Output lesson). If you want to create PDF’s locally, you’ll have to install Typst. The \n\nTypst installation instructions provides several options to install Typst: we strongly recommend using the latest releases.\n\nIf you get a confusing error, a good first step is to upgrade your version of Typst.","type":"content","url":"/software#pdf-generation-with-typst","position":23},{"hierarchy":{"lvl1":"Jupyter Book 2 Workshop Template"},"type":"lvl1","url":"/","position":0},{"hierarchy":{"lvl1":"Jupyter Book 2 Workshop Template"},"content":"","type":"content","url":"/","position":1},{"hierarchy":{"lvl1":"Jupyter Book 2 Workshop Template","lvl2":"Jupyter Book 2 Workshop Template"},"type":"lvl2","url":"/#jupyter-book-2-workshop-template","position":2},{"hierarchy":{"lvl1":"Jupyter Book 2 Workshop Template","lvl2":"Jupyter Book 2 Workshop Template"},"content":"\n\n\n\nA GitHub Template repository designed for use in Jupyter Book 2 and MyST workshops.\n\nFreek Pols, Luuk Fröling, Robert Lanzafame, Kirstie Whitaker, Jim Madge","type":"content","url":"/#jupyter-book-2-workshop-template","position":3}]}