Merge branch 'release' into Jessyink

Bump teachbooks from 0.2.5 to 0.2.7

.github/workflows/call-deploy-book.yml

@@ -5,7 +5,7 @@ on:
     branches:
     - '**'
     # - '!dependabot**'
-    # If your git repository has the Jupyter Book within some-subfolder next to
+    # If your git repository has the TeachBooks / Jupyter Book v1 within some-subfolder next to
     # unrelated files, you can make this run only if a file within that specific
     # folder (or the workflow file itself) has been modified.
     #

.gitignore

@@ -137,4 +137,7 @@ _output/
 book/.jupyterlite.doit.db
 
 # TeachBooks
-**.teachbooks/
+**.teachbooks/
+book/_toc_with_local_paths.yml
+book/_git/
+book/conf.py

.gitmodules

@@ -18,10 +18,6 @@
 	path = book/external/Sphinx-Image-Inverter
 	url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git
         branch = Manual
-[submodule "book/external/JupyterBook-Patches"]
-	path = book/external/JupyterBook-Patches
-	url = https://github.com/TeachBooks/JupyterBook-Patches.git
-        branch = manual_docs
 [submodule "book/external/Download-Link-Replacer"]
 	path = book/external/Download-Link-Replacer
 	url = https://github.com/TeachBooks/Download-Link-Replacer.git
@@ -58,3 +54,7 @@
 	path = book/external/Sphinx-PRIME-applets
 	url = https://github.com/TeachBooks/Sphinx-PRIME-applets.git
 	branch = manual
+[submodule "book/external/JupyterBook-Patches"]
+	path = book/external/JupyterBook-Patches
+	url = https://github.com/TeachBooks/JupyterBook-Patches.git
+	branch = manual_docs

CITATION.cff

@@ -0,0 +1,51 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+message: 'If you use this Book, please cite it using these metadata.'
+authors:
+  - email: info@teachbooks.io
+    name: 'TeachBooks Development Team'
+    website: 'https://teachbooks.io/'
+title: 'TeachBooks Manual source code'
+preferred-citation:
+  type: book
+  authors:
+  - email: info@teachbooks.io
+    name: 'TeachBooks Development Team'
+    website: 'https://teachbooks.io/'
+  url: 'https://doi.org/10.5281/zenodo.15100847' 
+  identifiers:
+    - type: doi
+      value: 10.5281/zenodo.15100848
+      description: Zenodo record
+    - type: url
+      value: 'https://teachbooks.io/manual/'
+      description: 'Published book on GitHub Pages'
+    - type: url
+      value: 'https://github.com/TeachBooks/manual'
+      description: 'GitHub repository'
+  abstract: >-
+    his manual assists you in creating and collaborating on TeachBooks
+    for educational purposes. Some parts are specifically aimed for
+    teachers at Delft University of Technology, although all material and
+    tools are openly available. This manual aims at providing an easy start
+    and advanced usages for new and existing users with or without skills
+    on this topic. 
+  keywords:
+    - TeachBooks
+    - Manual
+    - 'Jupyter Book'
+  title: 'TeachBooks Manual'
+  institution:
+    name: 'TeachBooks'
+  license: CC-BY-4.0
+  license-url: 'https://creativecommons.org/licenses/by/4.0/'
+  copyright: '© 2025 TeachBooks'
+  version: v1.2.1
+  date-released: '2025-03-28'
+  languages:
+    - en
+  contact:
+  - email: info@teachbooks.io
+    name: 'TeachBooks Development Team'

CODEOWNERS

@@ -0,0 +1,2 @@
+# All files in the repo
+* @Tom-van-Woudenberg

README.md

@@ -1,15 +1,16 @@
 # TeachBooks Manual
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848)
 [![call-deploy-book](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml)
 
-This manual assists you in creating and collaborating on [JupyterBooks](https://jupyterbook.org/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/).
+This manual assists you in creating and collaborating on TeachBooks: [JupyterBooks v1](https://jupyterbook.org/v1/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/).
 
 ## Contact
 If you encounter any issues and you have a TU Delft account, report it by clicking  the github icon and lightbulb on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://github.com/Teachbooks/manual).
 
 If you have questions, contact the TeachBooks Development Team at info@teackbooks.io, also for non-TU Delft account holders. You can also contact us in our [GitHub discussions](https://github.com/orgs/TeachBooks/discussions)
 
-We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
+We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own TeachBooks and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
 
 ## Contribute
 This book will continue to develop, so feel free to contribute https://github.com/TeachBooks/manual! You can do so directly by forking this repository and creating a merge request.
@@ -19,3 +20,4 @@ The released book can be found on on https://teachbooks.io/manual. This page sho
 Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this book including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git`
 
 Happy book building!
+

WAIVER

@@ -0,0 +1,4 @@
+Technische Universiteit Delft hereby disclaims all copyright interest in the
+program “TeachBooks Manual” (a book serving as documentation for various tooling
+surrounding TeachBooks) written by the Author(s).
+Stefan Aarninkhof, Dean of Civil Engineering & Geosciences

book/_config.yml

@@ -1,8 +1,8 @@
 title: TeachBooks Manual
-author: TeachBooks Team, built with <a href="https://teachbooks.io/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
+author: TeachBooks Development Team and TeachBooks users, built with <a href="https://teachbooks.io/">TeachBooks</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
 
 execute:
-  execute_notebooks: 'off'
+  execute_notebooks: 'auto'
 
 only_build_toc_files: true
 
@@ -14,16 +14,11 @@ sphinx:
   extra_extensions:
   - sphinx_inline_tabs
   - sphinx.ext.imgconverter
-  - download_link_replacer
+  - teachbooks_favourites
-  - jupyterbook_patches
   - teachbooks_sphinx_grasple
-  - sphinx_image_inverter
+  - sphinx_apa_references
-  - sphinx_exercise
-  - sphinx_proof
-  - sphinx_named_colors
-  - sphinx_iframes
-  - sphinx_prime_applets
   config:
+    language: en
     html_js_files:
     - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
     thebe_config:
@@ -45,17 +40,23 @@ sphinx:
     html_show_copyright: false
     html_last_updated_fmt: '%B %-d, %Y'
     html_static_path: ["images"]
-    bibtex_default_style: myapastyle
-    bibtex_reference_style: author_year_round
     mathjax3_config:
       tex:
         macros:
           "newcolor": ['\definecolor{newcolor}{RGB}{111, 29, 119}{\color{newcolor}#1}',1]
-    named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160]}
+    named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160],'attributiongrey':[150,150,150]}
-  local_extensions:
+    metadata_figure_settings:
-    apastyle: _ext/
+      style: 
-    bracket_citation_style: _ext/
+        placement: hide
+      license:
+        summaries: false
+        individual: false
+    nb_execution_includepatterns: "**/MANUAL.ipynb"
+    git_show_all_authors: true
 
+teachbooks:
+  attribution_location: margin
+  attribution_color: attributiongrey
 
 bibtex_bibfiles: 
   - references.bib

book/_ext/apastyle.py

@@ -1,17 +0,0 @@
-
-# from pybtex.style.formatting.unsrt import Style
-from pybtexapastyle.formatting.apa import APAStyle
-from pybtexapastyle.labels.apa import LabelStyle as APALabelStyle
-from pybtex.plugin import register_plugin
-# from pybtex.style.template import names, sentence
-
-class MyAPALabelStyle(APALabelStyle):
-    def format_label(self, entry):
-        return APALabelStyle.format_label(self, entry)
-
-class MyAPAStyle(APAStyle):
-    default_label_style = 'myapa'
-
-def setup(app):
-    register_plugin('pybtex.style.labels', 'myapa', MyAPALabelStyle)
-    register_plugin('pybtex.style.formatting', 'myapastyle', MyAPAStyle)

book/_ext/bracket_citation_style.py

@@ -1,27 +0,0 @@
-from dataclasses import dataclass, field
-import sphinxcontrib.bibtex.plugin
-
-from sphinxcontrib.bibtex.style.referencing import BracketStyle
-from sphinxcontrib.bibtex.style.referencing.author_year import AuthorYearReferenceStyle
-
-
-def bracket_style() -> BracketStyle:
-    return BracketStyle(
-        left='(',
-        right=')',
-    )
-
-
-@dataclass
-class MyReferenceStyle(AuthorYearReferenceStyle):
-    bracket_parenthetical: BracketStyle = field(default_factory=bracket_style)
-    bracket_textual: BracketStyle = field(default_factory=bracket_style)
-    bracket_author: BracketStyle = field(default_factory=bracket_style)
-    bracket_label: BracketStyle = field(default_factory=bracket_style)
-    bracket_year: BracketStyle = field(default_factory=bracket_style)
-
-
-def setup(app):
-    sphinxcontrib.bibtex.plugin.register_plugin(
-        'sphinxcontrib.bibtex.style.referencing',
-        'author_year_round', MyReferenceStyle)

book/_ext/pybtexapastyle/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2018 Naeka
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

book/_ext/pybtexapastyle/formatting/apa.py

@@ -1,486 +0,0 @@
-# -*- coding:Utf-8 -*-
-from __future__ import unicode_literals
-
-import re
-import six
-
-from pybtex.plugin import find_plugin
-from pybtex.style.formatting import BaseStyle, toplevel
-from pybtex.style.template import (
-    field, first_of, href, join, optional, optional_field, sentence, tag,
-    together, words, node, FieldIsMissing
-)
-
-from pybtex.richtext import Text, Symbol
-
-
-firstlast = find_plugin('pybtex.style.names', 'lastfirst')()
-
-if six.PY2:
-    def format_pages(text):
-        dash_re = re.compile(r'-+')
-        pages = Text(Symbol('ndash')).join(
-            re.split(dash_re, six.text_type(text)))
-        if re.search('[-‒–—―]', six.text_type(text)):
-            return Text("pp.", Symbol('nbsp'), pages)
-        return Text("p.", Symbol('nbsp'), pages)
-else:
-    def format_pages(text):
-        dash_re = re.compile(r'-+')
-        pages = Text(Symbol('ndash')).join(text.split(dash_re))
-        if re.search('[-‒–—―]', str(text)):
-            return Text("pp.", Symbol('nbsp'), pages)
-        return Text("p.", Symbol('nbsp'), pages)
-
-
-pages = field('pages', apply_func=format_pages)
-date = words[field('year'), optional[", ", field('month')]]
-
-
-@node
-def apa_names(children, context, role, **kwargs):
-    """
-    Returns formatted names as an APA compliant reference list citation.
-    """
-    assert not children
-
-    try:
-        persons = context['entry'].persons[role]
-    except KeyError:
-        raise FieldIsMissing(role, context['entry'])
-
-    style = context['style']
-
-    if len(persons) > 7:
-        persons = persons[:6] + persons[-1:]
-        formatted_names = [style.format_name(
-            person, style.abbreviate_names) for person in persons]
-        return join(sep=', ', last_sep=', … ')[
-            formatted_names].format_data(context)
-    else:
-        formatted_names = [style.format_name(
-            person, style.abbreviate_names) for person in persons]
-        return join(sep=', ', sep2=', & ', last_sep=', & ')[
-            formatted_names].format_data(context)
-
-
-@node
-def editor_names(children, context, with_suffix=True, **kwargs):
-    """
-    Returns formatted editor names for inbook.
-    """
-    assert not children
-
-    try:
-        editors = context['entry'].persons['editor']
-    except KeyError:
-        raise FieldIsMissing('editor', context['entry'])
-
-    formatted_names = [
-        firstlast.format(editor, True) for editor in editors]
-
-    if with_suffix:
-        return words[
-            join(sep=', ', sep2=', & ', last_sep=', & ')[formatted_names],
-            "(Eds.)" if len(editors) > 1 else "(Ed.)"
-        ].format_data(context)
-
-    return join(sep=', ', sep2=', & ', last_sep=', & ')[
-        formatted_names
-    ].format_data(context)
-
-
-class APAStyle(BaseStyle):
-    name = 'apa'
-    default_name_style = 'lastfirst'
-    default_sorting_style = 'author_year_title'
-    default_label_style = 'apa'
-
-    def __init__(self, *args, **kwargs):
-        super(APAStyle, self).__init__(*args, **kwargs)
-        self.abbreviate_names = True
-
-    def format_names(self, role, as_sentence=True):
-        formatted_names = apa_names(role)
-        if as_sentence:
-            return sentence(capfirst=False)[formatted_names]
-        else:
-            return formatted_names
-
-    def format_author_or_editor_and_date(self, e):
-        if 'author' in e.persons and 'editor' in e.persons:
-            return sentence(sep=' ')[
-                self.format_names('author'), join["(", date, ")."],
-                self.format_editor(e, as_sentence=False)]
-        elif 'author' in e.persons:
-            return sentence(sep=' ')[
-                self.format_names('author'), join["(", date, ")"]]
-        else:
-            return sentence(sep=' ')[
-                self.format_editor(e, as_sentence=False),
-                join["(", date, ")"]]
-
-    def format_editor(self, e, as_sentence=True):
-        editors = self.format_names('editor', as_sentence=False)
-        if 'editor' not in e.persons:
-            # when parsing the template, a FieldIsMissing exception
-            # will be thrown anyway; no need to do anything now,
-            # just return the template that will throw the exception
-            return editors
-        if len(e.persons['editor']) > 1:
-            word = '(Eds.)'
-        else:
-            word = '(Ed.)'
-        result = join(sep=' ')[editors, word]
-        if as_sentence:
-            return sentence[result]
-        else:
-            return result
-
-    def format_volume(self, e, for_article=False):
-        prefix = "Vol."
-        if for_article:
-            return join[
-                tag('em')[field('volume')],
-                optional['(', field('number'), ')'],
-            ]
-        else:
-            return optional[together[prefix, field('volume')]]
-
-    def format_title(self, e, which_field, as_sentence=True):
-        formatted_title = field(
-            which_field, apply_func=lambda text: text.capitalize()
-        )
-        if as_sentence:
-            return sentence[formatted_title]
-        else:
-            return formatted_title
-
-    def format_btitle(self, e, which_field, as_sentence=True):
-        formatted_title = tag('em')[field(which_field)]
-        if as_sentence:
-            return sentence[formatted_title]
-        else:
-            return formatted_title
-
-    def format_web_refs(self, e):
-        # Based on urlbst output.web.refs
-        return sentence(add_period=False)[
-            optional[self.format_url(e)],
-            optional[self.format_eprint(e)],
-            optional[self.format_pubmed(e)],
-            optional[self.format_doi(e)],
-        ]
-
-    def format_url(self, e):
-        # Based on urlbst format.url
-        return words[
-            'URL:',
-            href[
-                field('url', raw=True),
-                field('url', raw=True)
-            ]
-        ]
-
-    def format_pubmed(self, e):
-        # Based on urlbst format.pubmed
-        return href[
-            join[
-                'https://www.ncbi.nlm.nih.gov/pubmed/',
-                field('pubmed', raw=True)
-            ],
-            join[
-                'PMID:',
-                field('pubmed', raw=True)
-            ]
-        ]
-
-    def format_doi(self, e):
-        # Based on urlbst format.doi
-        return href[
-            join[
-                'https://doi.org/',
-                field('doi', raw=True)
-            ],
-            join[
-                'doi:',
-                field('doi', raw=True)
-            ]
-        ]
-
-    def format_eprint(self, e):
-        # Based on urlbst format.eprint
-        return href[
-            join[
-                'https://arxiv.org/abs/',
-                field('eprint', raw=True)
-            ],
-            join[
-                'arXiv:',
-                field('eprint', raw=True)
-            ]
-        ]
-
-    def get_article_template(self, e):
-        # Required fields: author, title, journal, year
-        # Optional fields: volume, number, pages, month, note, key
-        volume_and_pages = first_of[
-            # Volume and pages, with optional issue number
-            optional[
-                join[
-                    self.format_volume(e, for_article=True),
-                    optional[', ', field('pages')]
-                ],
-            ],
-            # Pages only
-            pages,
-        ]
-        template = toplevel[
-            self.format_names('author'),
-            sentence[
-                join["(", date, ")"]
-            ],
-            self.format_title(e, 'title'),
-            sentence[
-                tag('em')[field('journal')],
-                optional[volume_and_pages],
-            ],
-            sentence[optional_field('note')],
-            self.format_web_refs(e),
-        ]
-        return template
-
-    def get_book_template(self, e):
-        # Required fields: author/editor, title, publisher, year
-        # Optional fields: volume, series, address, edition, month, note, key,
-        #                  isbn
-        return toplevel[
-            self.format_author_or_editor_and_date(e),
-            sentence(sep=' ')[
-                self.format_btitle(e, 'title'),
-                optional[
-                    sentence[
-                        optional[field('edition'), ' ed.'],
-                        self.format_volume(e),
-                    ]
-                ]
-            ],
-            sentence(sep=': ')[
-                optional_field('address'),
-                field('publisher'),
-            ],
-            sentence[optional_field('note')],
-        ]
-
-    def get_booklet_template(self, e):
-        # Required fields: title
-        # Optional fields: author, howpublished, address, month, year, note,
-        #                  key
-        return toplevel[
-            sentence(sep=' ')[
-                first_of[
-                    optional[self.format_names(
-                        'author', as_sentence=False)],
-                    "None to claim their bones"
-                ],
-                join["(", first_of[optional[date], "n.d."], ")"]
-            ],
-            self.format_title(e, 'title'),
-            sentence[optional_field('address')],
-            sentence[optional_field('note')],
-        ]
-
-    def get_inbook_template(self, e):
-        # Required fields: author/editor, title, chapter/pages, publisher, year
-        # Optional fields: volume, series, address, edition, month, note, key
-        return toplevel[
-            sentence(sep=' ')[
-                self.format_names('author'),
-                join["(", date, ")"]
-            ],
-            self.format_title(e, 'title'),
-            sentence(sep=' ')[
-                optional[
-                    "In ",
-                    editor_names(),
-                    ","
-                ],
-                self.format_btitle(e, 'booktitle', as_sentence=False),
-                optional[
-                    join[
-                        "(",
-                        sentence(add_period=False)[
-                            optional[field('edition'), ' ed.'],
-                            self.format_volume(e),
-                            pages,
-                        ],
-                        ")"
-                    ]
-                ]
-            ],
-            sentence(sep=': ')[
-                optional_field('address'),
-                field('publisher'),
-            ],
-            sentence[optional_field('note')],
-        ]
-
-    def get_incollection_template(self, e):
-        # Required fields: author, title, booktitle, year
-        # Optional fields: editor, pages, organization, publisher, address,
-        #                  month, note, key
-        return toplevel[
-            self.format_author_or_editor_and_date(e),
-            self.format_title(e, 'title'),
-            sentence(sep=' ')[
-                self.format_btitle(e, 'booktitle', as_sentence=False),
-                optional["(", pages, ")"]
-            ],
-            sentence(sep=': ')[
-                optional_field('address'),
-                optional_field('publisher'),
-            ],
-            sentence[optional_field('note')],
-        ]
-
-    def get_inproceedings_template(self, e):
-        # Required fields: author, title, booktitle, year
-        # Optional fields: editor, pages, organization, publisher, address,
-        #                  month, note, key
-        return toplevel[
-            self.format_author_or_editor_and_date(e),
-            self.format_title(e, 'title'),
-            sentence(sep=' ')[
-                self.format_btitle(e, 'booktitle', as_sentence=False),
-                optional["(", pages, ")"]
-            ],
-            sentence(sep=': ')[
-                optional_field('address'),
-                optional_field('publisher'),
-            ],
-            sentence[optional_field('note')],
-            self.format_web_refs(e)
-        ]
-
-    def get_manual_template(self, e):
-        # Required fields: title
-        # Optional fields: author, organization, address, edition, month, year,
-        #                  note, key
-        return toplevel[
-            sentence(sep=' ')[
-                first_of[
-                    optional[self.format_names('author', as_sentence=False)],
-                    optional_field('organization'),
-                    "None to claim their bones"
-                ],
-                join["(", first_of[optional[date], "n.d."], ")"]
-            ],
-            self.format_btitle(e, 'title'),
-            sentence[optional_field('address')],
-            sentence[optional_field('note')],
-            self.format_web_refs(e)
-        ]
-
-    def get_mastersthesis_template(self, e):
-        # Required fields: author, title, school, year
-        # Optional fields: address, month, note, key
-        return toplevel[
-            sentence(sep=' ')[
-                self.format_names('author'),
-                join["(", date, ")"]
-            ],
-            sentence(sep=' ')[
-                self.format_btitle(e, 'title', as_sentence=False),
-                "(Master's thesis)"
-            ],
-            sentence[
-                field('school'),
-                optional_field('address'),
-            ],
-            sentence[optional_field('note')],
-        ]
-
-    def get_misc_template(self, e):
-        # Required fields: aucun
-        # Optional fields: author, title, howpublished, month, year, note, key,
-        #                  type
-        template = toplevel[
-            sentence(sep=' ')[
-                first_of[
-                    optional[self.format_names('author', as_sentence=False)],
-                    optional_field('publisher'),
-                    "None to claim their bones"
-                ],
-                join["(", first_of[optional[date], "n.d."], ")"]
-            ],
-            optional[self.format_title(e, 'title')],
-            sentence[optional_field('note')],
-            self.format_web_refs(e)
-        ]
-        return template
-
-    def get_phdthesis_template(self, e):
-        # Required fields: author, title, school, year
-        # Optional fields: address, month, note, key
-        return toplevel[
-            sentence(sep=' ')[
-                self.format_names('author'),
-                join["(", date, ")"]
-            ],
-            sentence(sep=' ')[
-                self.format_btitle(e, 'title', as_sentence=False),
-                "(Doctoral dissertation)"
-            ],
-            sentence[
-                field('school'),
-                optional_field('address'),
-            ],
-            sentence[optional_field('note')],
-        ]
-
-    def get_proceedings_template(self, e):
-        # Required fields: title, year
-        # Optional fields: editor, publisher, organization, address, month,
-        #                  note, key
-        return toplevel[
-            sentence(sep=' ')[
-                first_of[
-                    optional[self.format_editor(e, as_sentence=False)],
-                    optional_field('organization'),
-                    "None to claim their bones"
-                ],
-                join["(", first_of[optional[date], "n.d."], ")"]
-            ],
-            self.format_btitle(e, 'title'),
-            sentence(sep=': ')[
-                optional_field('address'),
-                optional_field('publisher'),
-            ],
-            sentence[optional_field('note')],
-        ]
-
-    def get_techreport_template(self, e):
-        # Required fields: author, title, institution, year
-        # Optional fields: type, number, address, month, note, key
-        return toplevel[
-            sentence(sep=' ')[
-                self.format_names('author', as_sentence=False),
-                join["(", date, ")"]
-            ],
-            self.format_btitle(e, 'title'),
-            sentence[field('institution')],
-            sentence[optional_field('note')],
-        ]
-
-    def get_unpublished_template(self, e):
-        # Required fields: author, title, note
-        # Optional fields: month, year, key
-        template = toplevel[
-            sentence(sep=' ')[
-                self.format_names('author', as_sentence=False),
-                join["(", first_of[optional[date], "n.d."], ")"]
-            ],
-            self.format_btitle(e, 'title'),
-            sentence[field('note')],
-        ]
-        return template

book/_ext/pybtexapastyle/formatting/pybtex/style/formatting/__init__.py

@@ -1,69 +0,0 @@
-from __future__ import unicode_literals
-
-from pybtex.style import FormattedEntry, FormattedBibliography
-from pybtex.style.template import node, join
-from pybtex.richtext import Symbol
-from pybtex.plugin import Plugin, find_plugin
-
-
-@node
-def toplevel(children, data):
-    return join(sep=Symbol('newblock')) [children].format_data(data)
-
-
-class BaseStyle(Plugin):
-    """
-    The base class for pythonic formatting styles.
-    """
-
-    default_name_style = None
-    default_label_style = None
-    default_sorting_style = None
-
-    def __init__(self, label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs):
-        self.name_style = find_plugin('pybtex.style.names', name_style or self.default_name_style)()
-        self.label_style = find_plugin('pybtex.style.labels', label_style or self.default_label_style)()
-        self.sorting_style = find_plugin('pybtex.style.sorting', sorting_style or self.default_sorting_style)()
-        self.format_name = self.name_style.format
-        self.format_labels = self.label_style.format_labels
-        self.sort = self.sorting_style.sort
-        self.abbreviate_names = abbreviate_names
-        self.min_crossrefs = min_crossrefs
-
-    def format_entries(self, entries, bib_data=None):
-        sorted_entries = self.sort(entries)
-        labels = self.format_labels(sorted_entries)
-        for label, entry in zip(labels, sorted_entries):
-            yield self.format_entry(label, entry, bib_data=bib_data)
-
-    def format_entry(self, label, entry, bib_data=None):
-            context = {
-                'entry': entry,
-                'style': self,
-                'bib_data': bib_data,
-            }
-            try:
-                get_template = getattr(self, 'get_{}_template'.format(entry.type))
-            except AttributeError:
-                format_method = getattr(self, "format_" + entry.type)
-                text = format_method(context)
-            else:
-                text = get_template(entry).format_data(context)
-            return FormattedEntry(entry.key, text, label)
-
-    def format_bibliography(self, bib_data, citations=None):
-        """
-        Format bibliography entries with the given keys and return a
-        ``FormattedBibliography`` object.
-
-        :param bib_data: A :py:class:`pybtex.database.BibliographyData` object.
-        :param citations: A list of citation keys.
-        """
-
-        if citations is None:
-            citations = list(bib_data.entries.keys())
-        citations = bib_data.add_extra_citations(citations, self.min_crossrefs)
-        entries = [bib_data.entries[key] for key in citations]
-        formatted_entries = self.format_entries(entries)
-        formatted_bibliography = FormattedBibliography(formatted_entries, style=self, preamble=bib_data.preamble)
-        return formatted_bibliography

book/_ext/pybtexapastyle/formatting/pybtex/style/sorting/__init__.py

@@ -1,12 +0,0 @@
-from __future__ import unicode_literals
-
-
-from pybtex.plugin import Plugin
-
-
-class BaseSortingStyle(Plugin):
-    def sorting_key(self, entry):
-        raise NotImplementedError
-
-    def sort(self, entries):
-        return sorted(entries, key=self.sorting_key)

book/_ext/pybtexapastyle/formatting/pybtex/style/sorting/author_year_title.py

@@ -1,39 +0,0 @@
-from __future__ import unicode_literals
-
-from pybtex.style.sorting import BaseSortingStyle
-
-class SortingStyle(BaseSortingStyle):
-
-    def sorting_key(self, entry):
-        if entry.type in ('book', 'inbook'):
-            author_key = self.author_editor_key(entry)
-        elif 'author' in entry.persons:
-            author_key = self.persons_key(entry.persons['author'])
-        else:
-            author_key = ''
-        return (author_key, entry.fields.get('year', ''), entry.fields.get('title', ''))
-
-    def persons_key(self, persons):
-        return '   '.join(self.person_key(person) for person in persons)
-
-    def person_key(self, person):
-        if person.prelast_names[0] != '{' and person.last_names[0] != '{' and person.first_names[0] != '{':
-            return '  '.join((
-                ' '.join(person.prelast_names + person.last_names),
-                ' '.join(person.first_names + person.middle_names),
-                ' '.join(person.lineage_names),
-            )).lower()
-        else:
-            return '  '.join((
-                ' '.join(person.first_names + person.middle_names),
-                ' '.join(person.prelast_names + person.last_names),
-                ' '.join(person.lineage_names),
-            )).lower()
-
-    def author_editor_key(self, entry):
-        if entry.persons.get('author'):
-            return self.persons_key(entry.persons['author'])
-        elif entry.persons.get('editor'):
-            return self.persons_key(entry.persons['editor'])
-        else:
-            return ''

book/_ext/pybtexapastyle/labels/apa.py

@@ -1,67 +0,0 @@
-# -*- coding:Utf-8 -*-
-from __future__ import unicode_literals
-
-from collections import Counter
-import re
-import unicodedata
-
-from pybtex.style.labels import BaseLabelStyle
-
-
-_nonalnum_pattern = re.compile('[^A-Za-z0-9 \-]+', re.UNICODE)
-
-
-def _strip_accents(s):
-    return "".join(
-        (c for c in unicodedata.normalize('NFD', s)
-            if not unicodedata.combining(c)))
-
-
-def _strip_nonalnum(parts):
-    """Strip all non-alphanumerical characters from a list of strings.
-
-    >>> print(_strip_nonalnum([u"ÅA. B. Testing 12+}[.@~_", u" 3%"]))
-    AABTesting123
-    """
-    s = "".join(parts)
-    return _nonalnum_pattern.sub("", _strip_accents(s))
-
-
-class LabelStyle(BaseLabelStyle):
-    def format_labels(self, sorted_entries):
-        labels = [self.format_label(entry) for entry in sorted_entries]
-        count = Counter(labels)
-        counted = Counter()
-        for label in labels:
-            if count[label] == 1:
-                yield label
-            else:
-                yield label # + chr(ord('a') + counted[label])
-                # counted.update([label])
-
-    def format_label(self, entry):
-        label = "Anonymous"
-        if 'author' in entry.persons:
-            label = self.format_author_or_editor_names(entry.persons['author'])
-        elif 'editor' in entry.persons:
-            label = self.format_author_or_editor_names(entry.persons['editor'])
-        elif 'organization' in entry.fields:
-            label = entry.fields['organization']
-            if label.startswith("The "):
-                label = label[4:]
-        return ''
-        # if 'year' in entry.fields:
-        #     return "{}, {}".format(label, entry.fields['year'])
-        # else:
-        #     return "{}, n.d.".format(label)
-
-    def format_author_or_editor_names(self, persons):
-        if len(persons)==1:
-            return _strip_nonalnum(persons[0].last_names)
-        elif len(persons)==2:
-            return "{} & {}".format(
-                _strip_nonalnum(persons[0].last_names),
-                _strip_nonalnum(persons[1].last_names))
-        else:
-            return "{} et al.".format(
-                _strip_nonalnum(persons[0].last_names))

book/_ext/pybtexapastyle/names/firstlast.py

@@ -1,39 +0,0 @@
-# -*- coding:Utf-8 -*-
-from __future__ import unicode_literals
-
-from pybtex.style.names import BaseNameStyle, name_part
-from pybtex.style.template import join
-
-
-class NameStyle(BaseNameStyle):
-
-    def format(self, person, abbr=False):
-        r"""
-        Format names similarly to {vv~}{ll}{, jj}{, f.} in BibTeX.
-
-        >>> from pybtex.database import Person
-        >>> name = Person(string=r"Charles Louis Xavier Joseph de la Vall{\'e}e Poussin")
-        >>> firstlast = NameStyle().format
-
-        >>> print(firstlast(name).format().render_as('latex'))
-        Charles Louis Xavier~Joseph de~la Vall{é}e~Poussin
-        >>> print(firstlast(name).format().render_as('html'))
-        Charles Louis Xavier&nbsp;Joseph de&nbsp;la Vall<span class="bibtex-protected">é</span>e&nbsp;Poussin
-
-        >>> print(firstlast(name, abbr=True).format().render_as('latex'))
-        C.~L. X.~J. de~la Vall{é}e~Poussin
-        >>> print(firstlast(name, abbr=True).format().render_as('html'))
-        C.&nbsp;L. X.&nbsp;J. de&nbsp;la Vall<span class="bibtex-protected">é</span>e&nbsp;Poussin
-
-        >>> name = Person(first='First', last='Last', middle='Middle')
-        >>> print(firstlast(name).format().render_as('latex'))
-        First~Middle Last
-        >>> print(firstlast(name, abbr=True).format().render_as('latex'))
-        F.~M. Last
-
-        """
-        return join[
-            name_part(abbr=abbr)[person.rich_first_names + person.rich_middle_names],
-            name_part(before=' ')[person.rich_prelast_names],
-            name_part(before=' ')[person.rich_last_names],
-        ]

book/_ext/pybtexapastyle/setup.py

@@ -1,27 +0,0 @@
-import setuptools
-
-
-setuptools.setup(
-    name='pybtex-apa-style',
-    version='1.3',
-    author='Naeka',
-    author_email='contact@naeka.fr',
-    description='Pybtex APA-like style',
-    url='https://github.com/naeka/pybtex-apa-style',
-    py_modules=['formatting.apa', 'labels.apa', 'names.firstlast'],
-    entry_points={
-        'pybtex.style.formatting': 'apa = formatting.apa:APAStyle',
-        'pybtex.style.labels': 'apa = labels.apa:LabelStyle',
-        'pybtex.style.names': 'firstlast = names.firstlast:NameStyle',
-    },
-    classifiers=(
-        'Operating System :: OS Independent',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'License :: OSI Approved :: MIT License',
-        'Operating System :: OS Independent',
-        'Topic :: Text Processing :: Markup',
-        'Topic :: Utilities',
-    ),
-)

book/_static/attribution.css

@@ -0,0 +1,4 @@
+/* Attribution */
+div.attribution > .admonition-title::after {
+    content: "\f10d";
+}

book/_static/figuurWidget.js

@@ -255,7 +255,7 @@ const createFigureReference = (path, name, caption) => {
         + "{numref}`{number} &lt" + name + "&gt`";
 }
 
-//Via https://jupyterbook.org/en/stable/content/references.html#reference-tables
+//Via https://jupyterbook.org/v1/content/references.html#reference-tables
 const createTableReference = (caption, name) => {
     return "<b> tabel code: </b><br/>"
     +"```{table} " + caption + "<br/>"

book/_static/remove_author.css

@@ -0,0 +1,4 @@
+/* Hide the default Jupyter Book author footer */
+.component-author {
+  display: none;
+}

book/_toc.yml

@@ -42,23 +42,16 @@ parts:
   - caption: Features
     chapters:
     - file: features/overview.md
-    - file: basic-features/overview.md
       sections:
-      - file: basic-features/jupyterbook.md
+      - file: features/teachbooks_intro.md
-      - file: basic-features/figures.md
+      - file: external/deploy-book-workflow/README.md
-      - file: basic-features/equations.md
+      - file: features/favourites.md
-      - file: basic-features/videos.md
+      - file: external/template/README.md
-      - file: basic-features/References.md
-      - file: basic-features/code.md
-      - file: basic-features/Code_block_figures
-      - file: basic-features/badges.md
-      - file: basic-features/banner
-        title: Banner or Announcement
     - file: features/easy-editing.md
       sections:
-      - file: external/template/README.md
+      - file: features/write_online.md
-      - file: features/teachbooks
+      - file: features/release_book_online.md
-      - file: external/deploy-book-workflow/README.md
+      - file: features/draft-release
       - file: features/pull_request_build.md
       - file: features/local_server
       - file: features/external_toc
@@ -88,30 +81,58 @@ parts:
       - file: features/Jessyink
       - file: features/jupyterquiz.ipynb
       - file: external/sphinx-iframes/README.md
+      - external: https://github.com/TeachBooks/Sphinx-Indexed-Definitions/blob/manual/README.md
       - file: external/Sphinx-PRIME-applets/README.md
+      - external: "https://github.com/TeachBooks/sphinx-code-examples/blob/main/MANUAL.ipynb"
+      - file: features/sphinx-proof.md
+      - external: "https://github.com/TeachBooks/Sphinx-NB-Execution-Patterns/blob/Manual/README.md"
+      - file: features/exercise.md
+      - external: https://github.com/TeachBooks/Sphinx-ref-graph/blob/manual/README.md
+      - external: https://github.com/TeachBooks/Sphinx-GitHub-Alerts/blob/main/README.md
+      - external: https://github.com/TeachBooks/Sphinx-Metadata-Figure/blob/main/MANUAL.ipynb
+      - external: https://github.com/TeachBooks/Sphinx-Gated-Directives/blob/main/MANUAL.md
+      - external: https://github.com/TeachBooks/TeachBooks-Questions/blob/main/MANUAL.md
+      - external: https://github.com/TeachBooks/TeachBooks-Fetch/blob/main/MANUAL.md
     - file: features/visuals.md
       sections:
+      - external: https://github.com/TeachBooks/Sphinx-Accessibility/blob/manual/README.md
       - file: external/Sphinx-Image-Inverter/README.md
       - file: external/JupyterBook-Patches/README.md
       - file: external/Sphinx-TUDelft-theme/README.md
       - file: external/teachbooks-sphinx-tippy/README.md
       - file: features/apa
       - file: external/Sphinx-Named-Colors/README.md
+      - external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md
+      - external: https://github.com/TeachBooks/Sphinx-Sticky-Margin/blob/main/MANUAL.md
     - file: features/students
       sections:
       - file: external/annotater/README.md
       - file: basic-features/hypothesis.md
-
+  - caption: Original Jupyter Book v1 and Sphinx Features
+    chapters:
+    - file: basic-features/overview.md
+      sections:
+      - file: basic-features/jupyterbook.md
+      - file: basic-features/figures.md
+      - file: basic-features/equations.md
+      - file: basic-features/videos.md
+      - file: basic-features/References.md
+      - file: basic-features/code.md
+      - file: basic-features/Code_block_figures
+      - file: basic-features/badges.md
+      - file: basic-features/banner
+        title: Banner or Announcement
   - caption: Examples
     chapters:
     - file: examples/overview.md
-    - file: examples/book_structure.md
+      sections:
-    - file: examples/live_code.md
+      - file: examples/book_structure.md
-    - file: examples/example_gumbel.ipynb
+      - file: examples/live_code.md
-    - file: examples/theory_questions.md
+      - file: examples/example_gumbel.ipynb
-    - file: examples/example_quiz_interactive.ipynb
+      - file: examples/theory_questions.md
-    - file: examples/coding_theory_widgets.ipynb
+      - file: examples/example_quiz_interactive.ipynb
-    - file: examples/parametric_questions.ipynb
+      - file: examples/coding_theory_widgets.ipynb
+      - file: examples/parametric_questions.ipynb
 
   - caption: Editing Tools
     chapters:
@@ -119,13 +140,14 @@ parts:
     - file: helper_code/intro.md
       sections:
       - file: helper_code/converter.md
+      - file: helper_code/move_images.md
       - file: external/Useful_python_code/snippit.ipynb
       - file: external/Useful_python_code/extensionfildownloadreturn.ipynb
       - file: external/Useful_python_code/figshrinker.ipynb
        
-  - caption: Miscallaneous
+  - caption: Miscellaneous
     chapters:
     - file: references.md
     - file: credits
     - file: changelog
-    - file: contact
+    - file: contact

book/basic-features/badges.md

@@ -1,6 +1,6 @@
 # Badges, Buttons & Icons
 
-<a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
+<a href="https://jupyterbook.org/v1/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
 
 (my_ref)=
 ## Badges
@@ -36,7 +36,7 @@ Here's an overview of all the available colours:
 
 ## Buttons
 
-Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
+Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book v1 supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
 
 The basic code syntax for creating a button is as follows:
 
@@ -49,13 +49,13 @@ The basic code syntax for creating a button is as follows:
     :color: primary
     ``` 
 ```
-
+[](../features/overview.md)
-```{button-ref} ../features/overview.md
+```{button-ref} feature_overview
 :color: secondary
 ``` 
 
 ```
-    ```{button-ref} ../features/overview.md
+    ```{button-ref} feature_overview
     :color: secondary
     ``` 
 ```
@@ -119,12 +119,12 @@ To add an icon, use the following syntax:
 
 **1. Image Icons**
 
-Let's have a look at the first sentence of this chapter again: <a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> provides a range of features which are visually appealing and functional.
+Let's have a look at the first sentence of this chapter again: <a href="https://jupyterbook.org/v1/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> provides a range of features which are visually appealing and functional.
 
 Here the Jupyter-book logo was inserted for a more professional look. It's including a link `href` and and image saved as `../images/logo-wide.svg`
 
 ```
-<a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> provides a range of features which are visually appealing and functional.
+<a href="https://jupyterbook.org/v1/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> provides a range of features which are visually appealing and functional.
 ```
 
 **2. SVG Icons**

book/basic-features/banner.md

@@ -1,6 +1,6 @@
 # Banners and Announcements
 
-A banner can be added to the top of a Jupyter Book: 
+A banner can be added to the top of a TeachBook: 
 
 ```{figure} banner_mude.png
 ---
@@ -10,7 +10,7 @@ name: banner_mude
 Example of a banner in the MUDE book.
 ```
 
-This is a commonly used feature, described in the [Jupyter Book manual here](https://jupyterbook.org/en/stable/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a Jupyter Book website (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
+This is a commonly used feature, described in the [Jupyter Book v1 manual here](https://jupyterbook.org/v1/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a TeachBook (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
 
 ```
 sphinx:

book/basic-features/code.md

@@ -2,13 +2,13 @@
 
 There are two main ways to include code: directly within a Markdown file or within a Jupyter notebook. More methods are available, but we don't include them here. The first option is great for including simple calculations, or generating simple figures when an image file is not practical. *More will be added later.*
 
-Note that if you are using a `*.ipynb` file or including a code snippet in a `*.md` file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the Jupyter Book.
+Note that if you are using a `*.ipynb` file or including a code snippet in a `*.md` file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the TeachBook.
 
-When making notebooks for the Book, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book. 
+When making notebooks for the TeachBook, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book.
 
-We can change how the compiler treats notebook cells by using cell tags. You can find a detailed explanation on cell tags [here](https://jupyterbook.org/en/stable/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs. 
+We can change how the compiler treats notebook cells by using cell tags. You can find a detailed explanation on cell tags [here](https://jupyterbook.org/v1/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs. 
 
-The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions [here](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags). 
+The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions [here](https://jupyterbook.org/v1/content/metadata.html#jupyter-cell-tags). 
 
 For example, the following tag is used to convert the code input into either a drop-down (`hide-input`) or make it invisible (replace `hide-input` with `remove-input`). Replace `input` with `output` to do the same with the cell output:
 ```

book/basic-features/equations.md

@@ -29,9 +29,11 @@ $$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}$$
 
 To number the equations and refer in text, you need to provide a label to the equation. Just put the label between brackets and place it after the last \$\$, like this:
 
-    $$
+```md
-        F = m \cdot a
+$$
-    $$ (newtons_second_law)
+    F = m \cdot a
+$$ (newtons_second_law)
+```
 
 Resulting in:
 
@@ -43,5 +45,5 @@ Equation {eq}`show_newtons_second_law` can now be referred to.
 
 > **Note**
 > 
-> The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).
+> The TeachBook uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).
 > 

book/basic-features/figures.md

@@ -2,29 +2,29 @@
 
 To add a figure, just copy the figure to the correct directory. Then, in your markdown file, include the figure as follows:
 
-````
+````md
-    ```{figure} <figurename>.png/.jpg
+```{figure} <figurename>.png/.jpg
-    ---
+---
-    height/width: <height or width in pixels>
+height/width: <height or width in pixels>
-    name: <name of the figure>
+name: <name of the figure>
-    align: left / center / right
+align: left / center / right
-    figclass: left blank or "margin"
+figclass: left blank or "margin"
-    ---
+---
-    <Figure caption>
+<Figure caption>
-    ```
+```
 ````
 
 For example: 
 
-````
+````md
-    ```{figure} ../images/TUDelft_logo_rgb.png
+```{figure} ../images/TUDelft_logo_rgb.png
-    ---
+---
-    width: 70%
+width: 70%
-    name: demoexample1
+name: demoexample1
-    align: center
+align: center
-    ---
+---
-    example 1: width (70%) as percentage, align center
+example 1: width (70%) as percentage, align center
-    ```
+```
 ````
 
 provides this output, which looks nice.
@@ -39,19 +39,19 @@ example 1: width (70%) as percentage, align center
 
 Using the name label, you can refer to the figure as done with {numref}`Figure {number} <demoexample1>`.
 
-You can find more documentation on including figures [here](https://jupyterbook.org/en/stable/content/figures.html).<br> 
+You can find more documentation on including figures [here](https://jupyterbook.org/v1/content/figures.html).<br> 
 
 There are many settings, for instance aligning right: 
 
-````
+````md
-    ```{figure} ../images/TUDelft_logo_rgb.png
+```{figure} ../images/TUDelft_logo_rgb.png
-    ---
+---
-    width: 50%
+width: 50%
-    name: demoexample2
+name: demoexample2
-    align: right
+align: right
-    ---
+---
-    example 2: width (50%) as percentage, align right
+example 2: width (50%) as percentage, align right
-    ```
+```
 ````
 
 with the result:
@@ -67,22 +67,22 @@ example 2: width (50%) as percentage, align right
 
 Aligning right can come with the potential downside (not always wanted) that text is wrapped around the figure. To avoid this one can use `<div>` elements, both before and after the text (make sure to leave an empty line after the `<div>`!):
 
-````
+````html
-    <div style="clear: both;">
+<div style="clear: both;">
-    and the output
+and the output
-    </div>
+</div>
-    <div style="clear: both;">
+<div style="clear: both;">
 
-    ```{figure} ../images/TUDelft_logo_rgb.png
+```{figure} ../images/TUDelft_logo_rgb.png
-    ---
+---
-    width: 50%
+width: 50%
-    name: demoexample3
+name: demoexample3
-    align: right
+align: right
-    ---
+---
-    example 3: width (50%) as percentage, align right with additional div style
+example 3: width (50%) as percentage, align right with additional div style
-    ```
+```
 
-    </div>
+</div>
 ````
 
 <div style="clear: both;">
@@ -108,16 +108,16 @@ including `figclass: margin` sets the figure to the column at the right.
 
 </div>
 
-````
+````md
-    ```{figure} demo97/demo97_figure1.jpg
+```{figure} demo97/demo97_figure1.jpg
-    ---
+---
-    figclass: margin
+figclass: margin
-    width: 50%
+width: 50%
-    name: demoexample2
+name: demoexample2
-   
+
-    ---
+---
-    example 2:including figclass: margin
+example 2:including figclass: margin
-    ```
+```
 ````
 
 <br>

book/basic-features/hypothesis.md

@@ -1,11 +1,13 @@
-# Making comments on the website: Hypothesis
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 1-5.
 ```
 
 {bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
+````
+
+# Making comments on the website: Hypothesis
 
 Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.
 

book/basic-features/jupyterbook.md

@@ -1,18 +1,17 @@
-# Anatomy of a Jupyter Book
+# Anatomy of a TeachBook
 
-To build a Jupyter Book, you need three things:
+To build a TeachBook, you need three things:
 
 1. A configuration file
 2. A table of contents
 3. Content
 
 ## The configuration file
-The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
+The configuration file of TeachBooks is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
 
 ```yaml
-title: Jupyter Book Manual
+title: TeachBook Manual
-author: Interactive Textbooks CiTG
+author: TeachBooks development team
-logo: images/TUDelft_logo_rgb.png
 copyright: CC BY-NC
 
 execute:
@@ -23,7 +22,7 @@ sphinx:
   - sphinx_inline_tabs
 ```
 
-Technically speaking, a `_config.yml` file is not required to build a Jupyter Book. If you don't make one, `jupyter book` will just use all default values. However, you should make a configuration file which includes at least the following settings:
+Technically speaking, a `_config.yml` file is not required to build a TeachBook. If you don't make one, your TeachBook will just use all default values. However, you should make a configuration file which includes at least the following settings:
 
 - `title`: the title of your book, which appears on the top-left of every page, under the logo.
 - `author`: authors of the book, which appears in the bottom margin of every page.
@@ -32,7 +31,7 @@ Technically speaking, a `_config.yml` file is not required to build a Jupyter Bo
 
 In addition, the following option can also be useful:
 
-- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book documentation](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution).
+- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book v1 documentation](https://jupyterbook.org/v1/content/execute.html#exclude-files-from-execution).
 
 
 ```{warning}
@@ -116,6 +115,9 @@ parts:
     - file: section_1_2
 ```
 
+#### Exercise
+Check out [this exercise](https://teachbooks.io/template/syntax_exercises/007.html) in the TeachBooks template to see for yourself how to structure files with titles!
+
 ### Including a chapter twice
 In some cases you want to include the same chapter in two different places in your book (for instance parts). However, you do not want to make the same adjustments in different files, the content should only 'live' in one place. The solution is to use `include`:
 

book/basic-features/overview.md

@@ -1,8 +1,10 @@
-# Original Jupyter Book and Sphinx Features
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
 ```
+````
 
-These pages will provide a list of some common, basic book features which are all available in the original <a href="https://jupyterbook.org/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> package. Additionally, this page includes also best-practices.
+# Overview
+
+These pages itemize some of the more common, basic book features which are all available in the original <a href="https://jupyterbook.org/v1/"><img  style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> package, without requiring any additional software. They are, of course, selected with teachers and teaching applications in mind. On each page best-practices are illustrated.

book/basic-features/utterances.md

@@ -1,11 +1,13 @@
-# Discussions in your book: Utterances
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
 
 {bdg-white}`GitHub app and Javascript script`
+````
+
+# Discussions in your book: Utterances
 
 [Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
 

book/basic-features/videos.md

@@ -13,9 +13,9 @@ kernelspec:
 
 # Videos
 
-Videos uploaded to YouTube can be embedded in the Jupyter Book. There are several ways to do so:
+Videos uploaded to YouTube can be embedded in the TeachBook. There are several ways to do so:
 
-**1.** To embed them in the Jupyter Book, first obtain the embedding link of the video. In order to do so, go to the *YouTube* page of the video (so not the Brightspace page), then click *share* in the description box. There should be a button *embed*, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following 
+**1.** To embed them in the TeachBook, first obtain the embedding link of the video. In order to do so, go to the *YouTube* page of the video (so not the Brightspace page), then click *share* in the description box. There should be a button *embed*, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following 
 
 ```
     <iframe

book/credits.md

@@ -5,11 +5,13 @@ You can refer to this book in its entirety as:
 
 > TeachBooks Development Team (2024), _TeachBooks Manual_. https://github.com/TeachBooks/manual. Retreived [Month, Year]. CC BY 4.0.
 
+This book is registered on Zenodo too: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848)
+
 The introduction, structure and decisions on content is done under direction of the TeachBooks Development Team. The content is written by many contributors, of which there are many.
 
-We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static after Spring 2025. You can refer to individual chapters or pages within this book as:
+We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. You can refer to individual chapters or pages within this book as:
 
-> `<Primary Author>` (2024), `<Title of Chapter or Page>`. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [`<date>`]).
+> `<Title of Chapter or Page>`. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [`<date>`]).
 
 Better yet, include a link to the specific commit! _If you know what this means, we assume you know how to do it._
 
@@ -54,6 +56,8 @@ The following pages are included directly from an external resource and is not e
 - Page [](./external/teachbooks-sphinx-tippy/README.md). Original content licensed under MIT license.
 - Page [](./external/template/README.md). Original content licensed under CC BY 4.0 license.
 - Page [](./external/Sphinx-Named-Colors/README.md). Original content licensed under MIT license.
+- Page [](indexed_defintions). Original content licensed under MIT license.
+- Page [](interactive_graph_content). Original content licensed under MIT license.
 - Pages [](./external/Useful_python_code/extensionfildownloadreturn.ipynb), [](./external/Useful_python_code/figshrinker.ipynb) and [](./external/Useful_python_code/snippit.ipynb). Original content licensed under BSD 3-Clause license.
 
 The following pages contain content written by others, part of has been reused and/or modified by the TeachBooks Team:
@@ -61,7 +65,6 @@ The following pages contain content written by others, part of has been reused a
 - Page {ref}`copyright_licenses`: {numref}`Figure %s<fig_license_types>` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY.
 - Page {ref}`copyright_licenses`: {numref}`Figure %s<fig_license_compatibility>` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024.
 - page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0.
-
+- page [](./features/external_toc.md): includes text from {cite:t}`teachbooks_package` that has been modified. Original content licensed under MIT.
-
+- Page [](./features/exercise.md): includes text from {cite:t}`sphinx-exercise` that has been modified. Original content licensed under MIT license.
-
+- Page [](./features/sphinx-proof.md): includes text from {cite:t}`sphinx-proof` that has been modified. Original content licensed under MIT license.
-

book/examples/book_structure.md

@@ -1,7 +1,7 @@
 # Well-Structured Book
 
 One thing that students love is having all practical information about a course collected and updated on one page.
-No more scrolling through the introduction lecture on Brightspace while veryfing assessment methods on the online studyguide or finding out about the schedule on MyTimetable. As will be shown in the following section, a Jupyter Book can be used to clarify the logistics of a course on top of providing the course material to the students.
+No more scrolling through the introduction lecture on Brightspace while veryfing assessment methods on the online studyguide or finding out about the schedule on MyTimetable. As will be shown in the following section, a TeachBook can be used to clarify the logistics of a course on top of providing the course material to the students.
 
 The crossover module Data Science and Artifical Intelligence for Engineers, or in short DSAIE, aims to teach powerful data science tools to 2nd master students from the Civil Engineering and Geosciences faculty. In order to do that they use a combination of practical projects and theory provided to the students through their online interactive [book](https://interactivetextbooks.citg.tudelft.nl/dsaie/intro.html). 
 
@@ -16,7 +16,7 @@ DSAIE Overview Page
 ```
 While the left menu shows the first two chapters in the table of contents (Home & Logistics), the right hand side menu shows the sections of the current chapter where an introduction is given on the different units of the course, the responsible lecturers as well as the schedule of lectures and practicals. Additionally, the book layout is explained to the students which can help clarify how to use the interactive sections! 
 
-The anatomy  of a jupyter book is explained more in detail on [this page](../basic-features/jupyterbook.md). In short, you can create structure in your book by having chapters and subschapters defined in the `.toc` file. In each chapter you can organize the content in sections using the `#` syntax which is visible in the menu on the right.
+The anatomy  of a TeachBook is explained more in detail on [this page](../basic-features/jupyterbook.md). In short, you can create structure in your book by having chapters and subschapters defined in the `.toc` file. In each chapter you can organize the content in sections using the `#` syntax which is visible in the menu on the right.
 
 ## Tagged content
 

book/examples/example_gumbel.ipynb

@@ -8,10 +8,10 @@
    "source": [
     "# Programming assignment with checks\n",
     "\n",
-    "This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n",
+    "This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a TeachBook format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n",
     "\n",
     "```{Note}\n",
-    "Keep in mind that Jupyter Book sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by jupyter book. In fact, in jupyter book, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.\n",
+    "Keep in mind that TeachBook sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by TeachBook. In fact, in a TeachBook, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.\n",
     "```\n",
     "\n",
     "```{custom_download_link} ./example_gumbel_stripped.ipynb\n",

book/examples/interactive_templates.md

@@ -4,10 +4,10 @@ Lastly some example pages are shown which combine theory and interactive questio
 
 1. [Programming Assignments](example_gumbel.ipynb)
 
-    This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding. 
+    This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a TeachBook format with live coding. 
 
 ```{Note}
-Keep in mind that Jupyter Book sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by jupyter book. In fact, in jupyter book, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.
+Keep in mind that TeachBook sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by TeachBook. In fact, in a TeachBook, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.
 ```
 
 2. [Combining theory with interactive questions and extensive coding assignments](example_quiz_interactive.ipynb)

book/examples/overview.md

@@ -1,7 +1,3 @@
-# TeachBooks Examples
+# Overview
-
-This chapter will showcase some TeachBooks making great use of Jupyter Book and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees. 
-
-
-
 
+This chapter will showcase some TeachBooks making great use of Jupyter Book v1 and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees. 

book/external/Download-Link-Replacer

@@ -1 +1 @@
-Subproject commit f69e970a8da7d85e5473c7e5f58299a2ee3cf331
+Subproject commit 03feccf6efa55d14da78cf4259cedb8a7585ad91

book/external/JupyterBook-Patches

@@ -1 +0,0 @@
-3a1ed3738693931fb735810cbc7a9a5734e85788

book/external/JupyterBook-Patches

@@ -0,0 +1 @@
+Subproject commit 99aeda40ae0cfa06eb290ba5c3a6b9b81eb3992d

book/external/Nested-Books

@@ -1 +1 @@
-Subproject commit a8e57da25302d47806ad1fe4288950c438562199
+Subproject commit c365e770730fb5abb3426b06062e69a3a325b336

book/external/Sphinx-Grasple-public

@@ -1 +1 @@
-Subproject commit f4eff8d1565eaf127898f2fe216cf5208684fb27
+Subproject commit 0dc28b45ef6184e67b8219bd4494c6f54ad8ccd0

book/external/Sphinx-Image-Inverter

@@ -1 +1 @@
-Subproject commit 250103c723aa782bcec785ae3d241cb1ffebd3d0
+Subproject commit ca1280ccadfc17f611b6f411dddb77329710dd85

book/external/Sphinx-Named-Colors

@@ -1 +1 @@
-Subproject commit 191c2f4ac1755d3b50c6a63950eb6c2e5c035d75
+Subproject commit 1307f44c8d64fb98ce4649f585805666e90ec3aa

book/external/Sphinx-PRIME-applets

@@ -1 +1 @@
-Subproject commit 43ea44ccdc917234513fcd0ea1b9d5159a7dc81f
+Subproject commit cf8849136e1303e1a2fa2a8ed7296cde6b3b2d68

book/external/Sphinx-TUDelft-theme

@@ -1 +1 @@
-Subproject commit e4b71f810a66e302243377876f39e1dc4c4a8a6b
+Subproject commit 3815645c5cfef3ebbdc8070e649e4c7331b680e3

book/external/Sphinx-launch-buttons

@@ -1 +1 @@
-Subproject commit ccec26fd77d3b6f1bb3415b5eb824b3155a397f1
+Subproject commit 9e70fbca8fb7bacb3e6d9c58349f04d6245082dc

book/external/Useful_python_code

@@ -1 +1 @@
-Subproject commit 7fbdbbf720c27112fb58bcf7826225197e39357b
+Subproject commit c80863d19f7fde7a452200baa4b4fafe12debc95

book/external/annotater

@@ -1 +1 @@
-Subproject commit 9340b4e2856b6f2de331c31d2b74bd9dc286d276
+Subproject commit d1f41f93ffe87a305956de405dac47daaad3bc69

book/external/deploy-book-workflow

@@ -1 +1 @@
-Subproject commit b9c76239ed042eb5befb6fa47f14d44de5113c51
+Subproject commit da54eb463cd0bac2a3e78dcce7067b2a81a8c3d1

book/external/sphinx-iframes

@@ -1 +1 @@
-Subproject commit 077ba23fa29ef1f0dd454f2ebf93c107923d1068
+Subproject commit 2bc21b6174b8e7dbd15c862c219bd506e06f9d13

book/external/teachbooks-sphinx-tippy

@@ -1 +1 @@
-Subproject commit 338ad14d39115c620c57476931ce8fa177cf20d8
+Subproject commit 6122c67f86a7c9b95f349c80316571e277f0a66b

book/external/template

@@ -1 +1 @@
-Subproject commit a8958fe48c839729226e1d1765dbf26617cf6c59
+Subproject commit 1ab90c5092b69aa8e1421e598ff43433bd97a9d8

book/features/HTML_javascript.md

@@ -1,4 +1,4 @@
-# Interactive HTML/JavaScript elements
+````{margin}
 
 ```{admonition} User types
 :class: tip
@@ -6,6 +6,9 @@ This section is useful for user type 5.
 ```
 
 {bdg-danger}`iframe`
+````
+
+# Interactive HTML/JavaScript elements
 
 In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
 

book/features/adding_HTML_elements.md

@@ -1,6 +1,8 @@
-# Adding interactive HTML/JavaScript elements
+````{margin}
-
 {bdg-danger}`iframe`
+```` 
+
+# Adding interactive HTML/JavaScript elements
 
 In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
 

book/features/apa.md

@@ -1,100 +1,133 @@
-(apa)=
+````{margin}
-# APA References
-
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4 and 5.
 ```
 
-{bdg-primary}`(To be converted into) Sphinx Extension`
+{bdg-primary}`Sphinx Extension`
 
-```{note}
+````
-This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more.
 
-The instructions provided here will work under conventional usage with Jupyter Book (e.g., `jupyter book build book`).
+(apa)=
-
+# APA References
-A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)).
-```
 
 ## Introduction
 
-Do you include references in your book, but you're tired of the default options available in Jupyter Book? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
+Do you include references in your book, but you're tired of the default options available in a TeachBook / Jupyter Book v1? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
 
 There is a solution! This extension allows you to have APA formatting in your book.
 
 ## Installation
-To use APA-references, a set of Python files need to be manually loaded into your book
 
-**Step 1: files to root directory of your book**
+To use APA-references, install the [Sphinx-APA-References extension](https://github.com/TeachBooks/Sphinx-APA-References) by following these two steps:
 
-Download this zip-file [`_ext.zip`](_ext.zip), which contains the necessary files, unzip it and place the contents in the root of your book directory so that it looks like the schematic here:
+**Step 1: Install the Package**
 
+Install the module `sphinx-apa-references` package using `pip`:
 ```
-book
+pip install sphinx-apa-references
-├── _ext/
-│   ├── pybtexapastyle/
-│   ├── apastyle.py
-│   ├── bracket_citation_style.py
-├── _config.yml
-├── _toc.yml
-├── requirements.txt
-├── <book files>
 ```
-
+    
 **Step 2: Add to `requirements.txt`**
 
-Add a specific version of `docutils` to your requirements file:
+Make sure that the package is included in your project's `requirements.txt` to track the dependency:
 ```
-docutils==0.17.1
+sphinx-apa-references
 ```
 
 **Step 3: Enable in `_config.yml`**
 
-In your `_config.yml` file, add a `bibtex_default_style`, `bybtex_reference_style` and the local extensions `apastyle` and `bracket_citation_style.py`
+In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time) and specify the location of your bib file (note indentation of the bibtex file path specification; any number of bib files are allowed):
 ```
-sphinx:
+sphinx: 
-  config:
+    extra_extensions:
-    ...
+        .
-    bibtex_default_style: myapastyle
+        .
-    bibtex_reference_style: author_year_round
+        .
-  local_extensions:
+        - sphinx_apa_references
-    apastyle: _ext/
+        .
-    bracket_citation_style: _ext/
+        .
-  ...
+        .
+bibtex_bibfiles: "<path_to_bib_file>/references.bib"
 ```
 
 ## Usage
 
-All references are now made in APA-style. See for example this reference: {cite:t}`jason_moore` which shows up on the [references page](../references.md) too. The form of the citation looks like this:
+All references are now made in APA-style. Here are five examples how to create a citation in APA style:
+
+| Syntax | Result with 1 author | Result with many authors | Explanation |
+| :---: | :---: | :---: | :---: |
+|`{cite:t}` | {cite:t}`jason_moore` | {cite:t}`dummyreference` | Textual citation |
+|`{cite:p}`| {cite:p}`jason_moore` | {cite:p}`dummyreference` | Parenthetical citation |
+|`{cite}`| {cite}`jason_moore` | {cite}`dummyreference` | Same as `{cite:p}` |
+|`{cite:ts}` | {cite:ts}`jason_moore` | {cite:ts}`dummyreference` | Same as `{cite:t}`, but without abbreviation of authors |
+|`{cite:ps}`| {cite:ps}`jason_moore` | {cite:ps}`dummyreference` |Same as `{cite:p}`, but without abbreviation of authors |
+
+For more options on the in-line citation style, see https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style.
+
+The references section at the end of your book will also be formatted in APA style:
+
+::::{admonition} Example of APA References
+:class: example
+
+```{iframe} ../references.html
+:class: no-blend
+```
+::::
+
+## Duplicate label warning
+
+You might encounter a warning during the build process that has this structure:
 
 ```
-{cite:t}`jason_moore`
+<filename>:<lineno>: WARNING: duplicate label "<authors>, <year>" for keys "<key1>" and "<key2>"
 ```
 
-Here are three examples for making citations:
+This is might have different cause, but often it is because two different references have the same author(s) and the same year. A common solution is to add letters to the year in the `.bib` file, like this:
 
-| Syntax | Result |
+```bibtex
-| :---: | :---: |
+@misc{launch_buttons,
-|`{cite:t}` | {cite:t}`jason_moore` |
+  author = {{TeachBooks}},
-|`{cite:p}`| {cite:p}`jason_moore` |
+  title = {Custom launch buttons},
-|`{cite}`| {cite}`jason_moore` |
+  url = {https://github.com/TeachBooks/Sphinx-launch-buttons},
+  year = {2024a},
+  note = {Retrieved December, 2024. BSD-3-Clause.},
+}
 
-For more options on the in-line citation style, see https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style.
+@misc{nested,
+  author = {{TeachBooks}},
+  title = {Git workflow: Share content between book},
+  url = {https://github.com/TeachBooks/Nested-Books},
+  year = {2024b},
+  note = {Retrieved December, 2024. CC BY 4.0.},
+}
 
-### Known Issues
+```
 
-Two issues are known:
+This does negate the automatic ordering of references by the order `authors > year > title`, so our advice is to only use this solution when the bibliography contains duplicate author-year combinations ánd the bibliography is final. That way the you can use the sorted order with warnings to determine the correct letters to add to the years.
-- During the build, warning will be raised with `... WARNING: duplicate label for keys ...`. In most cases, these warnings can be ignored. As noted above, the book will not build references properly 
-- In case you have both an `.ipynb` and `.md` version of a file, the `.md` version will always be used whenever this extension is used. This removes the possibility to show code outputs.
 
 ## Implementation
 
 The extension is based on [`pybtex`](https://pybtex.org/), which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins. 
 
-Although some customization is possible with the standard Jupyter Book features, [as described here](https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this).
+Although some customization is possible with the standard Jupyter Book v1 features, [as described here](https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style), this extension implements a complete APA style, as well as enforcing round brackets (like this).
 
-The need to enforce `docutils==0.17.1` version is the only known solution to the issue where empty brackets `[]` are left on the references page.
+### Previous implementation
 
-## Contribute
+APA referencing was previously implemented by including a local extension in a book subdirectory `_ext` (described [here](https://github.com/jupyter-book/jupyter-book/issues/1090)). To upgrade, once this Sphinx extension is implemented in your book, the local extension files in `_ext` can be deleted and the four lines indicated below removed from your `_config.yml` file:
 
-This tool needs to be developed further to make it into a proper sphinx-extension (and/or an independent `pybtext` plugin). The process is described in this [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17). If you've ideas or questions, please reach out to us at info@teachbooks.io!
+```yaml
+sphinx:
+  config:
+    .
+    .
+    .
+    bibtex_reference_style: author_year_round   # remove
+    bibtex_default_style: myapastyle            # remove
+    .
+    .
+    .
+  local_extensions:
+    apastyle: _ext/                             # remove
+    bracket_citation_style: _ext/               # remove
+```

book/features/buildbook.md

@@ -8,7 +8,7 @@ Now that we have talked about how you can collaborate using git, it's time to ex
 
 ## Pipeline
 
-Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
+Both GitLab and GitHub make use of CI/CD to publish the TeachBooks. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of TeachBooks, it focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
 
 Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML.
 

book/features/creating_basic_HTML_elements.md

@@ -53,7 +53,7 @@ The first few lines of our JavaScript code are simple. To scale our element with
          var width = vw;
          
          // Create the canvas. We will use only part of it for the main plot
-         var svg = d3.select("#click") // This selects the div
+         var svg = d3.select("#click") // This selects the svg using its id
              .attr("width", width) // This defines the canvas' width
              .attr("height", height) // This defines the canvas' height
 ```
@@ -853,4 +853,4 @@ Here is the code for the element above in full:
 </html>
 
 
-```
+```

book/features/custom-launch-button.md

@@ -1,12 +1,14 @@
-# Multilingual book
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4 and 5.
 ```
 {bdg-primary}`Sphinx Extension`
 
-The custom launch button extension allows you to create a customizable button in the top right of your jupyter book. 
+````
+
+# Multilingual book
+The custom launch button extension allows you to create a customizable button in the top right of your TeachBook. 
 This may have many applications, one of them being that you can create different language versions of the book available for the user. 
 
 This section will explain how to create a "Languages" or " <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16">

book/features/directories.py

@@ -0,0 +1,22 @@
+import os
+import json
+
+def list_file_types(directory):
+    file_types = set()
+    for root, _, files in os.walk(directory):
+        for file in files:
+            _, ext = os.path.splitext(file)
+            if ext:  # Only include files with extensions
+                file_types.add(ext)
+    return sorted(file_types)
+
+def format_file_types(file_types):
+    formatted = [f"**/*{ext}" for ext in file_types]
+    return formatted
+
+if __name__ == "__main__":
+    book_directory = r"c:\Users\tomvanwoudenbe\Git\book\book"
+    file_types = list_file_types(book_directory)
+    formatted_file_types = format_file_types(file_types)
+    print("File types in the directory (formatted):")
+    print(json.dumps(formatted_file_types))

book/features/draft-release.md

@@ -1,14 +1,34 @@
-(teachbooks-package)=
-# Draft-Release Workflow
 
-```{admonition} User types
+````{margin}
-:class: tip
+
+```{note}
+
+{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
+
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+
+{bdg-link-light}`Supported by Deploy Book workflow <../external/deploy-book-workflow/README.html>`
+
+```
+
+```{tip}
 This page is useful for user type 3-5.
 ```
 
-{bdg-secondary}`Python Package: teachbooks`
+```{seealso}
 
-Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow <deploy-book-workflow>`, which builds our TeachBooks).
+[{octicon}`mark-github` Repository](https://github.com/TeachBooks/teachbooks)
+
+[{octicon}`book` Documentation](https://teachbooks.readthedocs.io/latest/cli/cli.html)
+
+```
+
+````
+
+(draft-release)=
+# Draft-Release Workflow
+
+Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow <deploy-book-workflow>`, which builds our TeachBooks).
 
 ```{admonition} Why is this useful?
 :class: tip
@@ -24,7 +44,7 @@ The workflow is enabled by a `teachbooks` CLI feature that identifies and remove
 
 For example, pages in a developed book (e.g., `draft` branch) can be manually stripped out of the table of contents when a merge request from `draft` to `release` is made. This prevents the page being included in the released book. Pages marked with this feature are still visible in the `draft` book. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows:
 
-```
+```yaml
 format: jb-book
 root: intro
 
@@ -33,9 +53,9 @@ parts:
     chapters: 
     - file: ...
       ...
-# START REMOVE-FROM-PUBLISH
+# START REMOVE-FROM-RELEASE
     - file: files_to_remove
-# END REMOVE-FROM-PUBLISH
+# END REMOVE-FROM-RELEASE
 ```
 
 There is no limit to the number of stripped sections, they can be sequential and indentation does not matter.
@@ -43,9 +63,11 @@ There is no limit to the number of stripped sections, they can be sequential and
 To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package:
 
 ```
-teachbooks build --publish book
+teachbooks build --release book
 ```
 
+This is done in the [deploy-book-workflow](deploy-book-workflow) by including the branches for which preprocessing needs to be done the repository variable `BRANCHES_TO_PREPROCESS` which is by default set to ` ` (just a space = no branch). It should be a space-separated list of branch names, e.g. 'main second third'.
+
 Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter-book build book` would. This is called "draft mode" and is the default behavior. You can recognize it in the stdout after running the `build` command:
 
 ```bash
@@ -68,6 +90,6 @@ pip install --upgrade teachbooks
 
 We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow <deploy-book-workflow>`. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice.
 
-The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package.
+The package is a CLI tool that primarily provides a wrapper around the Jupyter Book v1 package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package.
 
-The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction.
+The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction.

book/features/easy-editing.md

@@ -1,8 +1,10 @@
-# Easy Editing Process
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
+````
+
+# Easy Editing Process
 
 The following tools are created by TeachBooks to ease the process of making books. We acknowledge that making books is a difficult process; it requires advanced knowledge on CLI, python packages, html-files, data-storage and website hosting. The tools in this chapter are intended for those users who lack knowledge on these topics (which includes most of the TeachBooks' community members itself).

book/features/exercise.md

@@ -0,0 +1,88 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses MIT licensed content from {cite:t}`sphinx-exercise`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+```
+
+```{admonition} User types
+:class: tip
+This section is useful for user type 3-5.
+```
++++
+{bdg-primary}`Sphinx Extension`
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`
+````
+
+# Sphinx exercise
+
+This extensions provides an easy way to add exercises and solutions to your book. It is created by the Executable Books team and is [documented here](https://ebp-sphinx-exercise.readthedocs.io/en/latest/).
+
+TeachBooks has made some small modifications to the original extension, such that it works well with translated books; this modified version is located in the repository [github.com/TeachBooks/sphinx-exercise](https://github.com/TeachBooks/sphinx-exercise).
+
+## What does it do?
+
+This extension defines exercises and solutions as new admonition types:
+
+```{exercise}
+:label: my-exercise
+
+Recall that $n!$ is read as "$n$ factorial" and defined as
+$n! = n \times (n - 1) \times \cdots \times 2 \times 1$.
+
+There are functions to compute this in various modules, but let's
+write our own version as an exercise.
+
+In particular, write a function `factorial` such that `factorial(n)` returns $n!$
+for any positive integer $n$.
+```
+
+````{solution} my-exercise
+:label: my-solution
+
+Here's one solution.
+
+```{code-block} python
+def factorial(n):
+    k = 1
+    for i in range(n):
+        k = k * (i + 1)
+    return k
+
+factorial(4)
+```
+````
+
+More information can be found in the [official documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/).
+
+## Installation
+To use this extenstion, follow these steps:
+
+**Step 1: Install the Package**
+
+Install the TeachBooks' version of  `sphinx-exercise` package using `pip`:
+```
+pip install sphinx-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.git
+```
+    
+**Step 2: Add to `requirements.txt`**
+
+Make sure that the package is included in your project's `requirements.txt` to track the dependency:
+```
+sphinx-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.git
+```
+
+**Step 3: Enable in `_config.yml`**
+
+In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
+```
+sphinx: 
+    extra_extensions:
+        .
+        .
+        .
+        - sphinx_exercise
+        .
+        .
+        .
+```

book/features/external_toc.md

@@ -1,29 +1,38 @@
-(external-toc)=
+````{margin}
-# Sharing content between books in table of contents
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses MIT licensed content from {cite:t}`teachbooks_package`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+```
 
 ```{admonition} User types
 :class: tip
 This page is useful for user type 3-5.
 ```
 
-{bdg-secondary}`Python Package: teachbooks`
+{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
+
+{bdg-success}`WebApp`
+````
+
+(external-toc)=
+# Sharing content between books in table of contents
 
 ## Introduction
 
-When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package.
+When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package, or by making use of the [TeachBooks Recombiner](https://teachbooks.io/recombiner/).
 
 Previously, this book feature was implemented using [submodules](../external/Nested-Books/README.md), but the implementation was more difficult to use. Despite this, submodules are still a widely used Git feature that can be very useful for book authors, so check out the [submodules page](../external/Nested-Books/README.md) to learn more, especially if the External TOC tool does not satisfy your needs. Submodules have a few additional features not (yet) implemented using the External TOC.
 
-```{warning}
+The External TOC features are incorporated in the teachbooks package starting with version `0.2.0`. The [TeachBooks Recombiner](https://teachbooks.io/recombiner/) is a webapp to ease that process.
-The External TOC features are not incorporated in the new deploy book workflow yet (this will happen once the workflow specifies `teachbooks>=0.2.0`).
-```
 
 ## What does it do?
 
-This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb`, `.md` and `.rst` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it validates that the external content has a permissive license, automatically combines any `reference.bib` files, and warns you if there's a mismatch in `requirements.txt` or with plugins in `_config.yml`.
+This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb`, `.md` and `.rst` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it validates that the external content has a permissive license, automatically combines any `reference.bib` files, and warns you if there's a mismatch in `requirements.txt` or with plugins in `_config.yml`. Furthermore, it adds an attribution admonition (like the one on this page) to the page, showing the source of the file in the built book.
+
+To ease the process, the webapp [TeachBooks Recombiner](https://teachbooks.io/recombiner/) allows you to select the pages to take from other books and generate the syntax to add them to your book.
 
 ## Installation
-To use this extenstion, follow these steps:
+To use this extension, follow these steps:
 
 **Step 1: Install the Package**
 
@@ -65,11 +74,49 @@ The link can be pointing to a file on a branch (which will take the most recent
 - `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` will take the file during the state of a specific commit (06d67e8).
 - `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` will take the file during the state of a specific tag (v1.1.1)
 
+These links can be created manually, copied from your browser, or generated using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). For the TeachBooks Recombiner: add the book you want to take content from, select the chapters and follow the instructions which gives you the syntax to add to your `_toc.yml`.
+
 If you're building your book online in GitHub, the [deploy-book-workflow](../external/deploy-book-workflow/README.md) will deal with these files during the `teachbooks build` command. If you want to build the book locally, run the command `teachbooks build`.
 
 If the source file is from another book, the contents of the `requirements.txt`, `_config.yml` are checked for any missing/incompatible entries. If this leads to compatibility issue, you'll be warned during the build which will help you solve these dependencies or plugins manually by updating your main book's `_config.yml` and `requirements.txt`
 Additionally, any `references.bib` files are merged into your main book's `references.bib` file, and the licenses of the external content are validated to allow for re-use. External content without a permissive license will result in an error to try to prevent any accidental copyright infringement.
 
+### Configuration
+The attribution admonition can be configured in the `_config.yml` file. You can adapt the location (top or margin), colour (making use of the sphinx extension [Sphinx-Named-Colors](../external/Sphinx-Named-Colors/README.md)), and symbol (by adding a custom CSS class). This leads to a similar admonition as mentioned [in the chapter on recommendations for copyright and licenses](custom_attribution).
+
+To adapt the location of the admonition (margin or top, top is default option), you can use the following configuration:
+
+```yaml
+teachbooks:
+  attribution_location: margin
+```
+
+To adapt the colour of the admonition (with for example a grey colour, default is blue), you can use the following configuration. Make sure to add the `sphinx-named-colors` extension to your environment (e.g., `requirements.txt`):
+
+```yaml
+sphinx:
+  config:
+    named_colors_custom_colors: {'attributiongrey':[150,150,150]}
+  extra_extensions:
+    - sphinx_named_colors
+
+teachbooks:
+  attribution_color: attributiongrey
+```
+
+To adapt the symbol of the admonition (with for example double quotes), you can add the following [custom CSS class](../_static/attribution.css) to `book/_static/attribution.css`:
+
+```css
+/* Attribution */
+div.attribution > .admonition-title::after {
+  content: "\f10d";
+}
+```
+
+Note that, when making a changes for the configuration locally they are not incorporated to existing external content.
+You will need to remove the `_git/` folder or run `teachbooks clean --external` and re-run the build command to see the changes. When building the book on i.e. GitHub Actions, the `_git/` folder is always rebuild from scratch.
+
+
 ## Contribute
 
 This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/TeachBooks).

book/features/favourites.md

@@ -0,0 +1,97 @@
+````{margin}
+
+```{note}
+{bdg-primary}`Sphinx Extension`
+
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+
+```
+
+```{tip}
+This page is useful for user type 3-5.
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository](https://github.com/TeachBooks/TeachBooks-Favourites)
+
+[{octicon}`pencil` Exercise](https://teachbooks.io/template/extension_exercises/017.html)
+
+```
+
+````
+
+# TeachBooks Favourites
+
+TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) or can be installed independently. The features included are:
+
+- [Sphinx-Thebe from TeachBooks](./live_code.ipynb)
+- [Jupyterbook patches](../external/JupyterBook-Patches/README.md)
+- [Download link replacer](../external/Download-Link-Replacer/README.md)
+- [Sphinx image inverter](../external/Sphinx-Image-Inverter/README.md)
+- [Sphinx iframes](../external/sphinx-iframes/README.md)
+- [Sphinx exercise (from Executable Books including TeachBooks contributions)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
+- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.md)
+- [Sphinx named colors](../external/Sphinx-Named-Colors/README.md)
+- [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md)
+- [Sphinx proof (from Executable Books including TeachBooks contributions)](https://sphinx-proof.readthedocs.io/en/latest/)
+- [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb)
+- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md)
+- [Sphinx toggle button (from Executable Books including TeachBooks contributions)](https://sphinx-togglebutton.readthedocs.io/en/latest/)
+- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md)
+- [Sphinx Launch Buttons](../external/Sphinx-launch-buttons/README.md)
+- [Sphinx GitHub Alerts](../_git/github.com_TeachBooks_Sphinx-GitHub-Alerts/main/README.md)
+- [Sphinx Metadata Figure](../_git/github.com_TeachBooks_Sphinx-Metadata-Figure/main/MANUAL.ipynb)
+- [Sphinx last updated by git (from Matthias Geier, TeachBooks version of the original)](https://github.com/TeachBooks/sphinx-last-updated-by-git)
+- [Sphinx Gated Directives](../_git/github.com_TeachBooks_Sphinx-Gated-Directives/main/MANUAL.md)
+- [Teachbooks Zoomies](https://github.com/TeachBooks/TeachBooks-Zoomies/)
+- [TeachBooks Questions](../_git/github.com_TeachBooks_TeachBooks-Questions/main/MANUAL.md)
+- [Sphinx Sticky Margin](../_git/github.com_TeachBooks_Sphinx-Sticky-Margin/main/MANUAL.md)
+- [TeachBooks Fetch](../_git/github.com_TeachBooks_TeachBooks-Fetch/main/MANUAL.md)
+- [Sphinx to do (from core sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html)
+
+The extension [Open in new tab](https://pypi.org/project/sphinx-new-tab-link/) is nice, but is not compatible with all setups (dependency clash) so is not included in TeachBooks-Favourites. 
+
+All features which are part of TeachBooks Favourites are include the following label on their respective pages in this manual: {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use.
+
+## Installation
+To install TeachBooks-Favourites, follow these steps:
+
+**Step 1: Install the Package**
+
+Install the `teachbooks-favourites` package using `pip`:
+```
+pip install git+https://github.com/TeachBooks/TeachBooks-Favourites
+```
+
+**Step 2: Add to `requirements.txt`**
+
+Make sure that the package is included in your project's `requirements.txt` to track the dependency:
+```
+git+https://github.com/TeachBooks/TeachBooks-Favourites
+```
+
+**Step 3: Enable in `_config.yml`**
+
+In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
+```
+sphinx: 
+    extra_extensions:
+        - teachbooks_favourites
+```
+
+## Usage
+
+For using the various package we refer to the different manuals linked above.
+
+All extensions are loaded with their default settings.
+
+## Contribute
+
+Do you think we missed an extension that should really be included? Let us know by either
+
+- creating a fork of this repository and submitting a pull request, in which you added the extension to the files
+  - `README.md`
+  - `pyproject.toml`
+  - `src\teachbooks_favourites\__init__.py`
+- opening an issue.

book/features/h5p.md

@@ -1,21 +1,25 @@
-# H5p interactive elements
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
 
 {bdg-danger}`iframe`
+````
+
+# H5p interactive elements
 
 ## Instruction
-H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. An H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):
+H5p elements are interactive HTML-blocks which can be embedded in a TeachBook using an iframe. H5p requires a server to host those elements. For TU Delft employees, this is arranged for on a [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first as described [here](https://www.tudelft.nl/teaching-support/educational-tools/h5p)).
+
+After creating an H5p element, the iframe code can be copied at Edit - Publish - Public - Embed code. This html link of that embed can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):
 
 ````
 ```{h5p} https://....h5p.com/content/.../embed
 ```
 ````
 
-Alternative, you can use raw html:
+Alternative, you can use raw html (lacking proper dark mode conversion):
 ```html
 <iframe src="https://....h5p.com/content/.../embed" aria-label="..." width="1088" height="200" frameborder="0" allowfullscreen="allowfullscreen" allow="autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *"></iframe><script src="https://tudelft.h5p.com/js/h5p-resizer.js" charset="UTF-8"></script>
 ```
@@ -37,4 +41,4 @@ Some best-practices on the use of H5p:
 
 In the next subpage, these exampled are shown.
 
-More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
+More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)

book/features/jupyterlite/configuration.md

@@ -23,9 +23,9 @@ When you have installed `jupyterlite-xeus-python`, the kernel will automatically
         }
     }
 
-## Updating the Jupyter Book `_config.yml`
+## Updating the TeachBook's `_config.yml`
 
-Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell Jupyter Book to include it in the build process and specify the name of the `jupyterlite` configuration file. To do so, create a new entry in `_config.yml` like this:
+Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell TeachBooks to include it in the build process and specify the name of the `jupyterlite` configuration file. To do so, create a new entry in `_config.yml` like this:
 
     sphinx:
         extra_extensions:
@@ -37,4 +37,4 @@ Of course, change `jupyterlite-config.json` to the name of your configuration fi
 
 ## Building
 
-When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `jupyter book build`. You can check this by keeping an eye on the output in the terminal: you should see a lot of extra lines mentioning `JupyterLite`.
+When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `teachbooks build`. You can check this by keeping an eye on the output in the terminal: you should see a lot of extra lines mentioning `JupyterLite`.

book/features/jupyterlite/jupyterlite.md

@@ -1,6 +1,6 @@
 # JupyterLite-Sphinx
 
-By popular demand: how to include interactive pieces of code in your Jupyter Book. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a Jupyter Book with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
+By popular demand: how to include interactive pieces of code in your TeachBook. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a TeachBook with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
 
 ## An example
 

book/features/jupyterquiz.ipynb

@@ -7,14 +7,16 @@
     "hidePrompt": true
    },
    "source": [
-    "# JupyterQuiz\n",
+    "````{margin}\n",
-    "\n",
     "```{admonition} User types\n",
     ":class: tip\n",
     "This section is useful for user type 4-5.\n",
     "```\n",
     "\n",
-    "- {bdg-secondary}`Python Package: jupyterquiz`\n",
+    "{bdg-secondary}`Python Package: jupyterquiz`\n",
+    "````\n",
+    "\n",
+    "# JupyterQuiz\n",
     "\n",
     "JupyterQuiz is a code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file. An example is given below:\n",
     "\n",

book/features/live_code.ipynb

@@ -4,16 +4,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Interactive content: Run Python inside your book\n",
+    "````{margin}\n",
-    "\n",
     "```{admonition} User types\n",
     ":class: tip\n",
     "This section is useful for user type 5.\n",
     "```\n",
     "\n",
     "{bdg-primary}`Sphinx Extension`\n",
+    "{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`\n",
+    "{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`\n",
     "\n",
-    "Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!\n",
+    "```` \n",
+    "\n",
+    "# Interactive content: Run Python inside your book\n",
+    "\n",
+    "Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a TeachBook with interactivity!\n",
     "\n",
     "This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n",
     "\n",
@@ -85,12 +90,12 @@
     "The `html_js_files` link calls for some required javascript files. `use_thebe_lite` makes sure you initiate our adapted sphinx thebe extensions. The `exclude_patterns` makes sure you import all files so that they can be accessed from your code, except for the files matching the patterns shown.\n",
     "\n",
     ":::{note}\n",
-    "If you've a lot of big files which are not used by the code, the build book repository might grow a lot in size. Include unnecessary filetypes like images (i.e. `\"**/*.png`) to `exclude_patterns`. Make sure you use proper markdown or MyST syntax for referencing to images. Using HTML code might lead to figures not being available in the final book.\n",
+    "If you've a lot of big files which are not used by the code, the build book repository might grow a lot in size. Include unnecessary filetypes like images (i.e. `\"**/*.png`) to `exclude_patterns`. Make sure you use proper markdown or MyST syntax for referencing to images. Using HTML code might lead to figures not being available in the final book. You can use [this python script](./directories.py) to list all filetypes in your book.\n",
     ":::\n",
     "\n",
     "By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. \n",
     "\n",
-    "Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/en/stable/basics/repository.html)).\n",
+    "Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book v1 documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/v1/basics/repository.html)).\n",
     "\n",
     "```yaml\n",
     "sphinx:\n",
@@ -114,7 +119,7 @@
     "If you push to main, you can test the interactivity on the book-draft website as well.\n",
     "\n",
     "## Custom cell tags\n",
-    "With the extended functionality of live code, additional cell tags have been developed to be added to python cells (not markdown cells) in any .ipynb file, next to the [existing tags] of the jupyter book (https://jupyterbook.org/en/stable/content/metadata.html):\n",
+    "With the extended functionality of live code, additional cell tags have been developed to be added to python cells (not markdown cells) in any .ipynb file, next to the [existing tags] of the jupyter book v1 (https://jupyterbook.org/en/stable/content/metadata.html):\n",
     "- `disable-execution-cell` disables the ability to execute the cell when thebe is activated. This might be useful if you notebook file includes interactivity for only a part of the coding cells\n",
     "- `disable-execution-page` disables the ability to execute the entire page. This might be useful if you use python code for creating a page, but the code is not part of the actual content of the book.\n",
     "- `auto-execute-page` automatically starts the thebe live coding functionality whenever the page is opened. This is particularly useful if you're using widgets on a page.\n",
@@ -171,6 +176,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "## Exercises and examples with executable code\n",
+    "\n",
+    "To include executable code in your book inside exercises and/or examples, you can use the Sphinx extension [Sphinx-Exercises](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#alternative-gated-syntax) and/or the Sphinx extension {ref}`Sphinx-Code-Examples <sphinx-code-examples-gated>`.\n",
+    "\n",
     "## Alternative with JupyterLite (less well integrated)\n",
     "\n",
     "Another option to use python in your browser is to use [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/). However, compared to Sphinx-Thebe, described above, this doesn't give a similar seamless interface within your page. Nevertheless, depending on your application, JupyterLite could be a useful tool, especially as it allows for three IDE types: Jupyter Notebook, Jupyter Lab and the iPython REPL.\n",
@@ -179,7 +188,7 @@
     "\n",
     "```{tip}\n",
     "The TeachBooks Team has focused primarily on the use of Sphinx-Thebe and has not looked at JupyterLite over the last couple years. If you have an interesting application of this tool for teaching, please get in touch, we would love to see it! You can use [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions) or sent us an email at [info@teachbooks.io](mailto:info@teachbooks.io).\n",
-    "```"
+    "```\n"
    ]
   }
  ],

book/features/local_server.md

@@ -1,12 +1,14 @@
-(setup-local-server)=
+````{margin}
-# Local Server to view interactive elements locally
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 4-5.
 ```
 
-{bdg-secondary}`Python Package: teachbooks`
+{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
+````
+
+(setup-local-server)=
+# Local Server to view interactive elements locally
 
 Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books.
 
@@ -15,7 +17,7 @@ Technically what is needed to facilitate this during the editing and checking of
 ```{admonition} Why do you need a local server?
 :class: tip
 
-A Jupyter Book is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly. 
+A TeachBook is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly. 
 ```
 
 We recommend you use the **TeachBooks Python Package**, which has a `serve` command in the CLI tool to start and stop local servers. Find out more on {ref}`the TeachBooks Package page <teachbooks-serve>`.
@@ -138,4 +140,4 @@ A Windows-specific command for the CMD prompt or Powershell is:
 
 ```
 TASKKILL /IM python.exe /F
-```
+```

book/features/overview.md

@@ -1,25 +1,30 @@
+(feature_overview)=
 # Overview
 
 As TeachBooks, we collect a suite of existing open-source software so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching!
 
 Since the list of TeachBook features is getting quite long, we have grouped them in categories:
-- Original Jupyter Book and Sphinx features
+- [Original Jupyter Book v1 and Sphinx features](../basic-features/overview.md)
-- Easy editing process
+- [Easy editing process](./easy-editing.md)
-- Additional functionality
+- [Additional functionality](./sphinx_extensions.md)
-- Book styling
+- [Book styling](./visuals.md)
-- TeachBooks student-view features
+- [TeachBooks student-view features](./students.md)
 
 Additionally, not all features are built and shared in the same way. We do our best to make sure that as many tools as possible are included automatically when using our TeachBooks Template Book; if you are not using the Template, we try to make sure each of our tools can be used independently. For transparency, tags will help differentiate between the different backgrounds of the features:
 - {bdg-warning}`Javascript overlay`
 - {bdg-success}`External software`
 - {bdg-white}`GitHub App and Javascript script`
-- {bdg-secondary}`Python Package: teachbooks`
+- {bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>`
-- {bdg-light}`GitHub Reusable Action`
+- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <../external/deploy-book-workflow/README.html>`
-- {bdg-light}`GitHub Template`
+- {bdg-link-light}`GitHub Template: TeachBooks Template <../external/template/README.html>`
 - {bdg-dark}`Git Workflow`
 - {bdg-primary}`Sphinx Extension`
+- {bdg-link-primary-line}`TeachBooks Favourites <./favourites.html>`
 - {bdg-danger}`iframe`
+- {bdg-success}`WebApp`
 
-Finally, the purpose, installation process and usage of each features is elaborated on in the respective sub-sections.
+For each feature, the purpose, installation process and usage is elaborated in the respective sub-sections.
 
-To see examples for these features, go to the [Examples chapter](../examples/overview.md).
+To see examples of these features, go to the [Examples chapter](../examples/overview.md).
+
+As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](../external/deploy-book-workflow/README.md), [TeachBooks Favourites](./favourites.md) and the [TeachBook template](../external/template/README.md) are important tools that incorporate and deploy more than one feature, an additional explanation is provided here in subpages to this page in more detail, with links to other pages in this manual where individual features are described.

book/features/plotly.ipynb

@@ -7,22 +7,66 @@
     "hidePrompt": true
    },
    "source": [
-    "# Interactive plots: plotly\n",
+    "````{margin}\n",
-    "\n",
     "```{admonition} User types\n",
     ":class: tip\n",
     "This section is useful for user type 5.\n",
     "```\n",
+    "````\n",
     "\n",
-    "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript."
+    "# Interactive plots: plotly\n",
+    "\n",
+    "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript. The example below is taken from the FEM-module by Frans van der Meer."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The example below is taken from the FEM-module by Frans van der Meer.\n",
+    "If you want to create the plot during the build of the book, don't use `fig.show()` but use the code below:"
-    "When using Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Alternatively, add the following lines of code to your notebook to have a valid output in the book as well:\n",
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from IPython.display import HTML\n",
+    "\n",
+    "def show_plotly(fig):\n",
+    "    # Use HTML when building book in CI environment\n",
+    "    if os.environ.get(\"CI\") == \"true\":\n",
+    "        return HTML(fig.to_html(include_plotlyjs=\"cdn\"))\n",
+    "\n",
+    "    # Local execution in Jupyter Notebook / JupyterLab / VS Code\n",
+    "    fig.show()\n",
+    "\n",
+    "....\n",
+    "\n",
+    "show_plotly(fig)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Make sure you have in your `_config.yml`:\n",
+    "\n",
+    "```yaml\n",
+    "execute:\n",
+    "  execute_notebooks: \"auto\"\n",
+    "```\n",
+    "\n",
+    "Eventually in combination with [](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Alternatively, you can run the notebook locally before building the book. This is not recommended for the combination with git because you will be committing binary output to the repository. When pre-generating Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Add the following lines of code to your notebook to have a valid output in the book as well:\n",
     "\n",
     "```python\n",
     "import plotly.io as pio\n",

book/features/pull_request_build.md

@@ -1,9 +1,11 @@
-# Build pull requests from forks
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
+````
+
+# Build pull requests from forks
 
 When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, **Read the Docs** is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page!
 
@@ -11,7 +13,7 @@ Pull Requests are a key tool for allowing anyone with a GitHub account to make a
 
 Read the Docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md).
 
-This tool works using Sphinx, which is the core engine for Jupyter Book; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
+This tool works using Sphinx, which is the core engine for Jupyter Book v1; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
 
 ```
 jupyter-book config sphinx book/

book/features/release_book_online.md

@@ -0,0 +1,257 @@
+````{margin}
+
+```{note}
+
+{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <../external/deploy-book-workflow/README.html>`
+
+{bdg-link-light}`Part of TeachBooks Template <../external/template/README.html>`
+
+{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
+
+```
+
+```{tip}
+This section is useful for user type 3-5.
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository deploy book workflow](https://github.com/TeachBooks/deploy-book-workflow)
+
+[{octicon}`book` Publish version on separate (fixed) URLs](../installation-and-setup/versions_URLs.md)
+
+{octicon}`pencil` Exercises:
+- [Your version of the book](https://teachbooks.io/template/exercises/004.html)
+- [Deploy book workflow](https://teachbooks.io/template/extension_exercises/015.html)
+
+```
+
+````
+
+# Share book online for multiple versions
+
+As you'll start working on your TeachBook, you'll probably want to share it online. And over time you'll create more and more versions of your book, for example for different academic years. 
+
+Our Deploy Book Workflow (described in general [here](../external/deploy-book-workflow/README.md)) allows you to do so. It builds your book for all branches in your repository and releases them online via GitHub Pages. In simplified terms, it automatically builds the book website based on updates to your repository, creates multiple instances of your book (defined by each branch) and provides the ability to customize the URL's at which each instance of the book can be accessed. This tool is designed specifically for educational contexts, for example, when you may want to preserve book versions from multiple academic years so that students are able to access it later.
+
+Sharing your book online has many features and customizations:
+- Automatic and manual building and releasing of your book online via GitHub Pages using a Reusable GitHub Actions. See explanation [below](how_to_start).
+- Ability to release both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories. GitHub Teams is free for teachers as described in the [GitHub documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers). If you have an organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the [GitHub website](https://github.com/team#organizations).
+- Releasing all or a selection of branches, allowing to build a draft version of the TeachBook online which reduces the need for local builds of the book. See explanation [below](gh-workflow-settings).
+- Allowing use of submodules within your book. For private submodules, see the explanation [below](private_submodules)
+- Converting branch-names to well-defined URLs. See explanation [below](gh-workflow-settings).
+- Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these settings are ill-defined or conflicting. Although aliases are generally not allowed by GitHub Pages, it seems you can use one alias, but not more. See explanation [below](gh-workflow-settings).
+- Customizable behavior of book URL root directory, either by redirecting the root to one of the branches or by copying or moving one of the branches to root. See explanation [below](gh-workflow-settings).
+- Adds an 'archived'-banner to old branches / branches of previous years. See explanation [below](gh-workflow-settings).
+- Custom 404 "Page Not Found" page with buttons for redirecting to Homepage (e.g., book intro page), "Go Back" or Repository home.
+- Provides a summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured. See explanation [below](gh-workflow-summary)
+- Caching of already built books so that it can be partially reused when another branch is released or the next build contains critical errors. See explanation [below](gh-caching)
+- Caching of python environment to speed up the workflow. See explanation [below](gh-caching)
+
+(how_to_start)=
+## How to start using this workflow
+
+The Deploy Book Workflow is by default incorporated into any book that has been created using the [TeachBooks Template](https://github.com/TeachBooks/template).
+
+Feel free to use it for your existing TeachBook as well:
+1. Add [`teachbooks`](https://github.com/TeachBooks/TeachBooks) to your `requirements.txt` file in your root folder
+2. Move all the TeachBook files (including `_config.yml` and `_toc.yml`) to a subdirectory `book/`.
+3. Copy the [`call-deploy-book.yml`](https://github.com/TeachBooks/template/blob/main/.github/workflows/call-deploy-book.yml) workflow to the `/.github/workflows` folder in your repository (the file is located in the TeachBooks Template repository becuase that file then refers to the file `deploy-book.yml` located in _this_ repository).
+4. Set source for GitHub pages to GitHub Actions under <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right">    <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` - <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-browser">    <path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25ZM14.5 6h-13v7.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25Zm-6-3.5v2h6V2.75a.25.25 0 0 0-.25-.25ZM5 2.5v2h2v-2Zm-3.25 0a.25.25 0 0 0-.25.25V4.5h2v-2Z"></path> </svg> `Pages` - `Build and deployment` - `Source` - `GitHub Actions` (as long as you don't do this the workflow deploys all branches which build successfully).
+5. Trigger the workflow by making an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-code UnderlineNav-octicon d-none d-sm-inline">    <path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path></svg> `Code`) or manually activating the workflow under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline">    <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions` - `All workflows` -  `call-deploy-book` - `Run workflow` - `Use workflow from branch: <the branch you did step 1, 2 and 3 in>` - `Run workflow` (this workflow).
+6. Now checkout the progress and summary of the releasing workflow under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline">    <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions` - `All workflows` -  `call-deploy-book` -`<the most recent workflow run>`.
+
+(gh-workflow-settings)=
+## Customize the workflow: TeachBook releasing settings
+You can adapt the behaviour by setting repository variables as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). Define the following repository variables:
+- `PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables.
+  - This sets the branch or alias (when using 'redirect' for `BEHAVIOR_PRIMARY`) which is shown on root.
+  - It is advised to show either your default branch on root, or the branch shared with your primary/active book audience (e.g., your current students).
+- `BEHAVIOR_PRIMARY` which is set to `redirect` whenever it's not defined in the repository variables.
+  - This indicates whether to copy the PRIMARY_BRANCH to root ('copy'), move the PRIMARY_BRANCH to root ('move') or redirect from root to the PRIMARY_BRANCH ('redirect')
+  - Advised to use 'redirect' if you expect to archive a version in the future so that the URL doesn't change for the reader (e.g., to preserve URL containing the current academic year shared with students).
+  - Use copy or move when you only expect readers to use the root URL. Move is useful to remove unnecessary build artifacts and if you don't need to visit the URL containing the branch or alias name.
+- `BRANCH_ALIASES` which is set to ` ` (just a space) whenever it's not defined in the repository variables.
+  - This defines an alias (custom URL) for a branch
+  - Variables should be a space-separated list of branch names, e.g. 'alias:really-long-branch-name`
+  - If no alias is wanted, `BRANCH_ALIASES` may be set to ` ` (just a space)
+- `BRANCHES_TO_DEPLOY`  which is set to `*` (all branches) whenever it's not defined in the repository variables.
+  - This defines the branches to deploy.
+  - It should be a space-separated list of branch names, e.g. 'main second third'.
+- `BRANCHES_TO_PREPROCESS` which is set to ` ` (just a space = no branch) whenever it's not defined in the repository variables
+  - This defines the branches to preprocess with the [`TeachBooks` package](./draft-release.md), which removed book-pages and config lines defined with `# START REMOVE-FROM-RELEASE` and `# END REMOVE-FROM-RELEASE`
+  - It should be a space-separated list of branch names, e.g. 'main second third'.
+  - If no preprocessing is required, `BRANCH_TO_PREPROCESS` may be set to ' ' (space).
+- `BRANCHES_ARCHIVED` which is set to ` ` (space, no branch) whenever it's not defined in the repository variables
+  - This adds a banner to the released branch: You are viewing an archived version of the book. Click here for the latest version.
+  - It should be a space-separate list of branch names, e.g. 'main second third'.
+
+In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch triggers the workflow. You can limit the branches or subdirectories.
+
+## Additional GitHub settings
+We advise  you to enable two options in the general repository setting regarding pull requests in GitHub:
+- Enable `Always suggest updating pull request branches`, suggesting a merge from the default branch into any separate branch before merging into main.
+- Enable `Automatically delete head branches` to delete branches after they are merged (you'll still be able to restore those).
+
+## Common Usage Examples
+
+Relevant use cases are explained here, along with an explanation for how to set up the workflow accordingly. Note that it is not required to set your `PRIMARY_BRANCH` to the default branch of your GitHub repository; this is a choice that is determined by what version of the source code you want visitors to see (i.e., work in progress, or the most recent "complete" or "released" version of a book).
+
+### Books with active users of different versions (academic years) 
+
+Consider a case where each academic year you would like to create a new book for your students. However, you need to ensure that students from previous years can still access "their" version of the book. 
+
+Assume for this example that we are working in the "my_organization" GitHub Organization in repository "my_book" and that the current academic year is 2025, and that we have one or more books in our repository from previous years. The desired URL structure is thus:
+- students from this year use the book at `my_organization.github.io/my_book/2025/`
+- students from last year use the book at `my_organization.github.io/my_book/2024/`
+- visitors to `my_organization.github.io/my_book/` will automatically be redirected to the book from the current year
+
+To create this behavior, do the following:
+
+- Create a branch for each year: a logical name would have format `YYYY`, (technically it can be anything, as the URL can be set to `YYYY` with `BRANCH_ALIASES`).
+- Set `PRIMARY_BRANCH` to the branch for the current academic year (e.g., `2025`)
+- Set `BEHAVIOR_PRIMARY` to `redirect` (default) 
+
+#### Alternative without redirect to current year
+
+One possible modification to this setup would be if you are progressively releasing content to your current students (e.g., `2025`) but you wanted visitors to `my_organization.github.io/my_book/` to see a complete version of your book. Assuming that the ideal version for such visitors is the completed book from the previous year (`2024`), you could do this:
+- Set `PRIMARY_BRANCH` to `2024`
+- Set `BEHAVIOR_PRIMARY` to `copy`
+
+As your current students may then accidentally go to the older version of the book, we recommend you use a banner to indicate to readers that there is a (partial) new version available, and advise them where to find it. You can add a banner using this workflow (`BRANCHES_ARCHIVED`) or the [standard Jupyter Book v1 banner feature](https://jupyterbook.org/v1/web/announcements.html).
+
+### Books with active editors working in parallel
+
+Consider a case where several authors are working on material for a book and you would like to be able to see the work of any author at any time. You also have a branch that is used to share finalized material with your readers (we call this a "release" branch) and a branch that is used to collect and review the work of all authors before releasing it (we call this a "draft" branch).
+
+Assume for this example that we are working in the "my_organization" GitHub Organization in repository "my_book." The released book is on branch `release` the draft book is on branch `draft`; author branches are `author_1`, `author_2`, etc. The desired URL structure is thus:
+- official (released) version of the book is at `my_organization.github.io/my_book/`
+- draft version of the book is at `my_organization.github.io/my_book/draft/`
+- the work of each author can be found at `my_organization.github.io/my_book/author_1/`, etc.
+
+To create this behavior, do the following:
+
+- Create a branch for each author as well as `release` and `draft` branches
+- Set `draft` to the default branch
+- Set `PRIMARY_BRANCH` to `release`
+- Set `BEHAVIOR_PRIMARY` to `copy`
+
+Note that in this situation we strongly recommend using the Draft-Release workflow that is incorporated in the TeachBooks Python package, which allows you to restrict specific content from appearing in the `release` book that is already incorporated in the `draft` book. [Find out more here](./draft-release.md). This is useful, for example, if you would like to review many chapters, but release only one at a time, or use a banner in the draft book (e.g., via `_config.yml`) but not the released book.
+
+#### Why make the draft branch default?
+
+What if you want to make sure the source code for the released book is visible in the repository, rather than the draft version (e.g., you want to make sure external visitors see this version of the material)? You can do this by making `release` your default branch instead of `draft`. However, this also means that Pull Requests will be default be made into the `release` branch instead of `draft`, which may alter the working method of your team in an undesirable way (e.g., not being able to use a `draft` branch, accidentally releasing material before checking on `draft`, or having to manually adjust every PR that is created by GitHub to merge into `draft` instead of `release`).
+
+(private_submodules)=
+## Private submodules
+In case your book includes private submodules, you'll need to create a Personal Access Token (classic) with at least the scope `repo` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` (<svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right">    <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` > <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-key-asterisk">    <path d="M0 2.75A2.75 2.75 0 0 1 2.75 0h10.5A2.75 2.75 0 0 1 16 2.75v10.5A2.75 2.75 0 0 1 13.25 16H2.75A2.75 2.75 0 0 1 0 13.25ZM2.75 1.5c-.69 0-1.25.56-1.25 1.25v10.5c0 .69.56 1.25 1.25 1.25h10.5c.69 0 1.25-.56 1.25-1.25V2.75c0-.69-.56-1.25-1.25-1.25Z"></path><path d="M8 4a.75.75 0 0 1 .75.75V6.7l1.69-.975a.75.75 0 0 1 .75 1.3L9.5 8l1.69.976a.75.75 0 0 1-.75 1.298L8.75 9.3v1.951a.75.75 0 0 1-1.5 0V9.299l-1.69.976a.75.75 0 0 1-.75-1.3L6.5 8l-1.69-.975a.75.75 0 0 1 .75-1.3l1.69.976V4.75A.75.75 0 0 1 8 4Z"></path></svg>`Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`.) Furthermore, manually copy the workflow (.github/workflows/deploy-book.yml) in your own repository as the authorization doesn't work with the called workflow.
+
+(gh-workflow-summary)=
+## View the workflow progress and summary
+
+Whenever the workflow is triggered, its progress and a summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline">    <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` -  `call-deploy-book` in GitHub! It shows you a descriptive summary:
+- Ill-defined repository configuration variables (in `Annotations`)
+- Which branches are released and where (`https://<username/organization_name>.github.io/<repository_name>` (case sensitive)) including which branch is released on the website root and the applied alias
+- Errors in the build process 
+- How the repository variables are defined during the build.
+
+Here's an example for a summary for the template book:
+
+> ### Branches deployed
+> | Branch 🎋 | Link 🔗 | Build status ☑️ |
+> | :--- | :--- | :--- |
+> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
+> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
+> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
+> 
+> #### Legend for build status
+> ✅ `Released` - build success, new version released.
+>
+> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
+>
+> ⭕ `Build failed [2]` - build failure, no previous version reused.
+>
+> #### Primary book at root
+> The book at the website root <https://teachbooks.github.io/template/> redirects to the primary branch `main` (status: ✅ `Released`).
+> 
+> ### Aliases
+> | Alias ➡️ | Target 🎯 | Link 🔗 |  Build status ☑️ |
+> | :--- | :--- | :--- | :---- |
+> | draft | main | [https://teachbooks.github.io/template/draft](https://teachbooks.github.io/template/draft) | ✅ `Released` |
+> 
+> ### Preview of build errors & warnings
+> For more details please see the corresponding `build-books` jobs in the left pane.
+>
+> On branch `version2`:
+> ```
+> <20>[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]<5D>[39;49;00m
+> ``` 
+>
+> On branch `version3`:
+> ```
+> /home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found
+> ```
+>
+> ### Repository configuration variables
+> Variables can be set at <https://github.com/TeachBooks/template/settings/variables/actions>
+>
+> ```
+> PRIMARY_BRANCH=main (default value used)
+> BRANCH_ALIASES=draft:main
+> BRANCHES_TO_DEPLOY=* (default value used)
+> BRANCHES_TO_PREPROCESS=main
+> BEHAVIOR_PRIMARY=redirect (default value used)
+> BRANCHES_ARCHIVED= (default value used)
+> ```
+
+(gh-caching)=
+## Caching
+
+The GitHub Action [Cache](https://github.com/actions/cache) is used in the Deploy Book Workflow (DBW) to save time when building the book. This is accompliched by caching two sets of files for each branch: 1) the Python virtual environment, and 2) the build artifact (the HTML files forming each book website).
+
+The reason for doing this stems from the primary purpose of the Deploy Book Workflow, which builds many versions of a book based on each branch, as well as creating a Python virtual environment from the `requirements.txt` file in the repository. A unique environment for each branch is necessary to test changes to book dependencies and configuration in an isolated way, but can dramatically increase the time required to build all versions of the book when the DBW runs. In addition, it also takes time to build the book itself. For this reason, both of these sets of files are cached (although at the moment, most of the time savings is primarily caching the build artifact).
+
+This works by hashing a specific set of files and including that in the filename of the cache. Every time the workflow is triggered, a new hashed filename is created and compared to the list of existing caches to see if one with the same name exists; if so, the cache is reused. If not, a new environment and/or build artifact is constructed and a new cache is made.
+
+Cached files can be found in GitHub under the Actions tab, then looking for the "Caches" section under the "Management" pane on the left hand side of the screen. For example, this link shows the [caches for this TeachBooks Manual](https://github.com/TeachBooks/manual/actions/caches). If needed, caches can be deleted manually from this page. A cache will expire if unused for longer than 1 week or if the maximum allowed disk space for all cached files is exceeded (both are GitHub policies).
+
+Files created during a GitHub Action are called [artifacts](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow). Although this is _not_ the same thing as a cache, the files in a specific cache or artifact are identical. Artifacts have their own expiration period, which is possible to [customize in the repository settings](https://docs.github.com/en/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization) (default is 90 days). Unexpired artifacts can be viewed at the bottom of any workflow run summary that is available on the Actions tab of a GitHub repository.
+
+To add even more confusion to the situation, if an artifact built during an Action is a set of HTML files (a website) that are used to create a GitHub Pages website, the files served when visiting the URL for that are stored on a webserver; they are _not_ the artifact files, but are identical. Fortunately webserver files are preserved indefinitely (or until GitHub changes this policy), meaning that even though your cache or artifact may be deleted, the website will still remain active.
+
+The cache is a key component of the DBW and leads to several considerations for the building and maintenance of a book, which are explained below, after the criteria for each cache type are described.
+
+### Cached Environment
+
+The DBW uses [Python virtual environments](https://docs.python.org/3/library/venv.html) (`python -m venv .venv`) and `python -m pip install -r requirements.txt` to install packages and create the book building environment. The entire `.venv` directory is preserved in the cache with a file name beginning with `venv-...`. The week number is also included in the file hash, which ensures that a new hash is created at least once per week.
+
+Once created during a successful build action, an existing cached environment will be found and reused unless two specific criteria are met: 1) a book build is required (replacing the cached build artifact), _and_ 2) the `requirements.txt` file is changed. Requirements for a "book build" are described in the next section.
+
+Note that any change to the `requirements.txt` file will trigger creation of a new environment, not necessarily one that specifies the version number of a package.
+
+Note that Specifying package version numbers explicitly and updating them via [Dependabot](./update_env.md) is an excellent way to ensure that environments in the DBW are always up to date and this issue is avoided.
+
+If you are _not_ using Dependabot and are not able to get your packages updated when the DBW is running, delete the cache manually and rerun your GitHub Actions job (go to Actions tab, then looking for the "Caches" section under the "Management" pane on the left hand side of the screen).
+
+### Cached Build Artifacts
+
+Build artifacts are the HTML files that define the website (i.e., the book) and are typically located in the subdirectory `book/_build/html` of a repository once the book is built. Note that these files are typically only visible if you are building the book locally, as they are not committed to the repository by default (i.e., `.gitignore`). For users only using the DBW and the GitHub browswer editor, downloading the build cache is the easiest way to view these files, which have filenames beginnig with `html-build-<branch-name>-...`.
+
+Once created during a successful build action, an existing cached build artifact will be found and reused unless _any_ of three specific criteria are met: 1) a change is made to a file in `book/`, 2) the `requirements.txt` file is changed, or 3) the status of a branch as archive or preprocess has changed (`BRANCHES_TO_PREPROCESS` of `BRANCHES_ARCHIVED`).
+
+Immediately after a successful build action, the book website files exist in three places: cache, artifact and on a GitHub webserver. However, as described at the beginning of this section, the cache will be automatically deleted after 1 week, if unused, and the artifact will be deleted based on the setting in your repository (90 days by default). 
+
+### Effect of Caching on Book Workflow
+
+Implementation of the DBW has several characteristics that should be noted which could help understand certain behaviors of the book build and website deployment process. These points may be useful to consider if you are experiencing undesired behavior in your Actions builds and/or your actual book websites.
+
+- Remember that the DBW action will only run if a commit is made that changes `requirements.txt` or contents of `book/`
+- When first creating a repository, the action may not run, or may run and fail; occasionally it is needed to make a new commit to get the workflow to run for the first time (remember to modify something in `book/`) or you may try to re-run the job from the Actions tab
+- when using multiple branches, only the branch that is edited will be updated
+- the website for each branch may be built with a different Python environments (different package versions)
+
+Unlike the virtual environments (next subsection), caches of the book build do not influence subsequent builds of the book, as this artifact is replaced whenever a commit to a specific branch triggers a new build process. As described above, old cached build artifacts are used if the build process from a new commit fails, ensuring that the URL of a website does not return a 404 page.
+
+### Effect of Caching on Virtual Environment
+
+In particular, note that older branches may have been built with cached environments that are different than those in a newer branch, leading to (undesired) differences in book appearance or functionality---often without the author being aware! This occurs if a package in `requirements.txt` is updated in the time between the creation of environments on different branches, as `pip` will use the newest version when downloading a package (the first time a venv cache is created in the DBW), but it will not always automatically update a package if `pip install -r requirements.txt` is used on an existing environment (this happens every time an existing cache is used!). This means that, when compared to the venv on a newer branch, a frequently used branch (where the cache has not expired) may retain old and out of date packages long after an updated version is available; however, since the week number is included in the venv file hash, this will last for a maximum of 1 week. A best practice to avoid this situation is to pin version numbers explicitly (e.g., `teachbooks==0.2.0`) if you want book builds to remain consistent. In addition, a feature like dependabot can be used to automatically notify you when an update is made; this is [here](./update_env.md).

book/features/sphinx-proof.md

@@ -0,0 +1,80 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses MIT licensed content from {cite:t}`sphinx-proof`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+```
+
+```{admonition} User types
+:class: tip
+This section is useful for user type 3-5.
+```
++++
+{bdg-primary}`Sphinx Extension`
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`
+````
+
+# Sphinx proof
+
+This extensions provides an easy way to add proofs, theorem, axioms and much more to your book. It is created by the Executable Books team and is [documented here](https://sphinx-proof.readthedocs.io/en/latest/).
+
+TeachBooks has made some small modifications to the original extension, such that it works well with translated books; this modified version is located in the repository [github.com/TeachBooks/sphinx-proof](https://github.com/TeachBooks/sphinx-proof).
+
+## What does it do?
+
+This extension defines proofs, theorems, axioms and other similar concepts as new admonition types:
+
+````{prf:example}
+:label: my-example
+
+Next, we shut down randomness in demand and assume that the demand shock
+$\nu_t$ follows a deterministic path:
+
+
+```{math}
+\nu_t = \alpha + \rho \nu_{t-1}
+```
+
+Again, we’ll compute and display outcomes in some figures
+
+```python
+ex2 = SmoothingExample(C2=[[0], [0]])
+
+x0 = [0, 1, 0]
+ex2.simulate(x0)
+```
+````
+
+More information can be found in the [official documentation](https://sphinx-proof.readthedocs.io/en/latest/index.html). It can be [configured in combination the TeachBooks extension to include examples with executable code and visuals](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb).
+
+## Installation
+To use this extenstion, follow these steps:
+
+**Step 1: Install the Package**
+
+Install the TeachBooks' version of  `sphinx-exercise` package using `pip`:
+```
+pip install sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git
+```
+    
+**Step 2: Add to `requirements.txt`**
+
+Make sure that the package is included in your project's `requirements.txt` to track the dependency:
+```
+sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git
+```
+
+**Step 3: Enable in `_config.yml`**
+
+In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
+```
+sphinx: 
+    extra_extensions:
+        .
+        .
+        .
+        - sphinx_proof
+        .
+        .
+        .
+```

book/features/sphinx_extensions.md

@@ -1,8 +1,10 @@
-# Additional functionality
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 4-5.
 ```
+````
 
-This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file.
+# Additional functionality
+
+This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions {bdg-primary}`Sphinx Extension`, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book v1 and TeachBooks is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of Jupyter Book and TeachBooks, as opposed to original jupyter-book v1 features, they must be installed and configured explicitly, for example in the `_config.yml` and `requirements.txt` files.

book/features/students.md

@@ -1,8 +1,11 @@
-# TeachBooks Student-view Features
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 1-5.
 ```
+````
+
+# TeachBooks Student-view Features
+
 
 This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach. These tools could also be useful for other users.

book/features/teachbooks_intro.md

@@ -0,0 +1,50 @@
+
+````{margin}
+
+```{note}
+
+{bdg-link-secondary}`Python Package: TeachBooks`
+
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+
+```
+
+```{tip}
+This section is useful for user type 4-5.
+
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository](https://github.com/teachbooks/teachbooks)
+
+[{octicon}`book` Documentation](https://teachbooks.readthedocs.io/)
+
+```
+
+````
+
+(teachbooks_package)=
+# TeachBooks Python Package
+
+The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book v1 software package by adding features and making customization easier. In general, it is only of interest to user types 4 and 5 when building a book locally. However, it may be important for other users to know what the package does, as it is incorporated in the [Deploy Book Workflow](../external/deploy-book-workflow/README.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points:
+
+1. If you are a book user using the [TeachBooks Template](../external/template/README.md) and/or the [Deploy Book Workflow](../external/deploy-book-workflow/README.md), your book is by default built with the `teachbooks` package, and the way your book is built and features that are included in the book may change automatically when it is updated (these will be non-breaking changes; if not, we will notify our mailing list).
+2. If you are using the `jupyter-book` v1 package to build your book, some of the features described in this Manual may not be available to you (i.e., those listed on this page). This will be the case if you are using a [setup described in the Jupyter Book v1 Manual](https://jupyterbook.org/v1/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/v1/publish/gh-pages.html).
+
+For those who wish to use the package, it is available on [PyPI](https://pypi.org/project/teachbooks/) and can be installed using `pip install teachbooks`. As `teachbooks` is a wrapper, the package is meant to replace the usage of `jupyter-book` commands (although it does indeed add a few new commands to the CLI, e.g., `serve`). It is conventionally used in an identical way, as follows: 
+
+```
+teachbooks build book
+```
+
+This Manual describes the main features and usage of the package. For those who wish to understand more of hte technical details, note that the implementation the API is is documented at [teachbooks.readthedocs.io/](https://teachbooks.readthedocs.io/).
+
+## List of Features
+
+Items in the list here are currently implemented in the TeachBooks package and described on other pages of this manual:
+- [Draft-Release Workflow](./draft-release.md)
+- [External Contents](./external_toc.md)
+- [Local Server](./local_server.md) 
+
+The package is also set up to handle [APA references](./apa) when using the Draft-Release Workflow (the `_ext` subdirectory and its contents are manually copied during the pre-build phase). This will not be necessary once the APA Reference feature is turned into a proper Sphinx extension or Pybtext plugin.

book/features/update_env.md

@@ -1,24 +1,29 @@
-# Auto-updating packages
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4-5.
 ```
 
 {bdg-dark}`Git Workflow`
+````
 
-When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options:
+# Auto-updating packages
-1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when new version come out, although new version are in general backwards compatible.
+
+When building your book, you are making use of various Python packages: the `teachbooks` and `jupyter-book` v1 packages themselves, but also packages for extensions. These are regularly updated, however, those updates are not necessarily incorporated into your book automatically. The list of packages and their versions are defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). Consider the following three options for how packages can be specified:
+1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when a new version has been released (although new versions will generally be backwards compatible).
 1. `requirements.txt` contains names of packages with a specified version like: `download_link_replacer==1.0.4`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) always uses that specific version. In doing so, you'll never get a new update unless you explicitly adapt the version in `requirements.txt`. If you'd like to get notified for updates, you might consider using GitHub's Dependabot.
-1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions. In this case you can also use GitHub's Dependabot.
+1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions.
+
+For the case of specified versions, you can use GitHub's Dependabot to notify you that a new version is available _and_ to automatically set up a Pull Request to update your book with the new version.
 
 ## Notifications updated packages with Dependabot
 
-Dependabot checks the specified version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available for that package. Note that package without a fixed version are ignored by Dependabot.
+Dependabot checks the specified version of packages in your `requirements.txt` file and, if a new version is found, will create a new branch, update the `requirements.txt` file and open a Pull Request whenever there's an update available for that package. Note that packages without a fixed version are ignored by Dependabot.
 
 To activate this feature:
 1. Specify version for all packages you want to be notified on in your `requirements.txt` file. See [`requirements.txt`](https://github.com/TeachBooks/manual/blob/release/requirements.txt) of this manual as an example
 1. In the `.github/` directory, add a file named `dependabot.yml` with the following content (note that sphinx-thebe (used in [python live coding](./live_code.ipynb)) and docutils (using in [APA referencing](./apa.md)) are ignored because these require a very specific version to work):
+
 ```yaml
 version: 2
 updates:
@@ -33,11 +38,12 @@ updates:
       - dependency-name: "docutils"
 ```
 
-This will check every sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
+This check will run every Sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
-1. A new branch starting with _dependabot_ will be created in the repository and any relevant workflows will be triggered.
+1. A new branch is created with a name that begins with `dependabot...` in the repository
-1.  A _pull request_ will be created to pull the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically).
+1. A commit is made updating `requirements.txt` (e.g., `jupyterbook_patches==1.4.2` is changed to `jupyterbook_patches==1.4.4`)
+1.  A _pull request_ will be created to merge the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically).
 
-If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want),  you can achieve this by adding the next to the file `call-deploy-book.yml`:
+Note that these activities will occur automatically and may trigger other workflows in your repository (for example, the building of a book on another branch). If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want), you can achieve this by adding the following text to the file `call-deploy-book.yml`:
 
 ```yaml
 on:

book/features/versioning.md

@@ -1,6 +1,10 @@
-# TeachBooks Versioning
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY 3.0 content from {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>````
+````
 
-> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+# TeachBooks Versioning
 
 Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors:
 
@@ -16,10 +20,11 @@ We have come up with guidelines how to use the two TeachBooks-versioning options
 3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version.
 4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented.
 5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented.
-6. Precedence refers to how versions are compared to each other when ordered.
+6. A pre-release version MAY be denoted by appending `.pre-release`. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is not complete.
+7. Precedence refers to how versions are compared to each other when ordered.
    1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order.
    2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1.
-7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
+8. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
 
 An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions.
 ````
@@ -35,4 +40,4 @@ An example can be seen in [the source repository of the Engineering Systems Opti
 ````
 `````
 
-Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases!
+Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases!

book/features/visuals.md

@@ -1,8 +1,10 @@
-# Book styling
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This section is useful for user type 1-5.
 ```
+````
+
+# Book styling
 
 TeachBooks developed a few improvements of the book which improve the visual book styling.

book/features/widgets.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Ipywidgets\n",
     "\n",
-    "If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](interactive_element).\n",
+    "If you publish widgets in a TeachBook they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](./plotly.ipynb).\n",
     "\n",
     "## `matplotlib` widgets\n",
     "When you'd like to use `ipywidgets` in combinations with a `matplotlib` figure, import the following packages:\n",
@@ -221,7 +221,7 @@
  "metadata": {
   "celltoolbar": "Tags",
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "base",
    "language": "python",
    "name": "python3"
   },
@@ -235,7 +235,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.5"
+   "version": "3.12.11"
   }
  },
  "nbformat": 4,

book/features/write_online.md

@@ -0,0 +1,82 @@
+````{margin}
+
+```{note}
+
+{bdg-link-light}`Uses Deploy Book workflow <../external/deploy-book-workflow/README.html>`
+
+{bdg-link-light}`Uses TeachBooks Template <../external/template/README.html>`
+
+```
+
+```{tip}
+This section is useful for user type 3-5.
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository deploy book workflow](https://github.com/TeachBooks/deploy-book-workflow)
+
+[{octicon}`mark-github` Repository template](https://github.com/TeachBooks/template)
+
+[{octicon}`book` Collaborative book-editing](../workflows/collaboration.md)
+
+{octicon}`pencil` Exercises:
+- [First file edit](https://teachbooks.io/template/exercises/001.html)
+- [Add a new file to the table of contents](https://teachbooks.io/template/exercises/002.html)
+- [Change book configuration](https://teachbooks.io/template/exercises/003.html)
+- [Syntax exercises](https://teachbooks.io/template/syntax_exercises.html)
+```
+
+````
+
+
+# Write book fully in GitHub interface
+
+Using the GitHub tooling in combination with TeachBook's software, users are able to write their book fully online, without the need to install any software locally. This is especially useful for users that are not familiar with Git and GitHub, or do not have the rights to install software on their computer. To make this possible, users can start with the [TeachBooks Template](../external/template/README.md) after which they make use of the [Deploy Book Workflow](../external/deploy-book-workflow/README.md) to automatically build and release their book online.
+
+## How to do this
+
+New users can start writing their book by following the steps shown in the [TeachBooks Template repository](https://github.com/TeachBooks/template).
+
+Users who already have a TeachBook repository can add the Deploy Book Workflow as explained [here](./release_book_online.md).
+
+After that, users can start writing and editing their book fully online in the GitHub interface. This is supported with:
+- Automatic book builds for all version. See [](./release_book_online.md) for more information
+- A summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured
+
+## Example of summary
+
+Whenever the workflow is triggered, its progress and a summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline">    <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` -  `call-deploy-book` in GitHub! It shows you a descriptive summary. This summary includes, among others, the errors in the build process per branch and where the book is released online.
+
+Here's an example for a summary for the template book:
+
+> ### Branches deployed
+> | Branch 🎋 | Link 🔗 | Build status ☑️ |
+> | :--- | :--- | :--- |
+> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
+> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
+> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
+> 
+> #### Legend for build status
+> ✅ `Released` - build success, new version released.
+>
+> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
+>
+> ⭕ `Build failed [2]` - build failure, no previous version reused.
+>
+> ### Preview of build errors & warnings
+> For more details please see the corresponding `build-books` jobs in the left pane.
+>
+> On branch `version2`:
+> ```
+> <20>[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]<5D>[39;49;00m
+> ``` 
+>
+> On branch `version3`:
+> ```
+> /home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found
+> ```
+>
+
+## Exercise
+Check out [the exercises](https://teachbooks.io/template/exercises.html) in the TeachBooks template to see for yourself how you can write and edit your book fully online in GitHub!

book/helper_code/converter.md

@@ -1,7 +1,7 @@
 (tex_md_converter)=
 # Convert LaTeX to Markdown
 
-A script is to convert LaTeX files to Markdown for use in Jupyter Books {cite:p}`timon_latex`.
+A script is to convert LaTeX files to Markdown for use in TeachBooks and Jupyter Books v1 {cite:p}`timon_latex`.
 
 This script has been used successfully on at least one book in the TU Delft OPEN library: [Introduction to particle and continuum mechanics, by Timon Idema](https://textbooks.open.tudelft.nl/textbooks/catalog/book/81). The author is able to convert nearly everything in this book automatically, with only a few manual adjustments needed (e.g., a special character and a figure caption).
 

book/helper_code/intro.md

@@ -1,7 +1,8 @@
 # Scripts for automating workflow
 
-This chapter contains a few scripts which can be useful in the book-editing process:
+This chapter contains a few scripts which can be useful in the book-editing process, all of which are scripts and/or files stored in other repositories  (they are _not_ Sphinx extensions).
- - [LaTeX to markdown conversion](tex_md_converter) to convert a LaTeX file into jupyter-book compatible markdown.
+
+ - [LaTeX to markdown conversion](tex_md_converter) to convert a LaTeX file into TeachBook compatible markdown.
  - [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder. 
  - [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder. 
  - [Extensionchecker](Extensionchecker) to identify the kind of files present in subfolder

book/helper_code/move_images.md

@@ -0,0 +1,3 @@
+# Move images to separate hosting
+
+Storing big binary files like images in your git repository and book is not good practice: diffs on binary files don't make sense and blow up the size of your repository. Furthermore, the size of your book website blows up too. Therefore, you can consider hosting your binary files on a different server, as explained [here in an example for the MUDE-book](https://tudelft-mude.github.io/teacher/FTP.html). To take all the images of your existing book and update the relative links, [a Python script](./parse_images.py) has been developed. This script processes Markdown (`.md`) and Jupyter Notebook (`.ipynb`) files listed in a `_toc.yml` file. It identifies local image references (including MyST `figure` syntax) in these files, copies the images to a specified folder (`new_images`), and replaces the local image paths with a public URL (e.g., `https://files.mude.citg.tudelft.nl/<image_name>`).

book/helper_code/parse_images.py

@@ -0,0 +1,207 @@
+"""
+Script: parse_images.py
+
+Description:
+This script processes Markdown (.md) and Jupyter Notebook (.ipynb) files listed in a `_toc.yml` file.
+It identifies local image references (including MyST `figure` syntax) in these files, copies the images
+to a specified folder (`new_images`), and replaces the local image paths with a public URL
+(e.g., `https://files.mude.citg.tudelft.nl/<image_name>`).
+
+Key Features:
+- Parses `_toc.yml` to extract all Markdown and Notebook files.
+- Detects image references in Markdown files (e.g., `![alt text](image.png "title")`).
+- Detects MyST `figure` syntax (e.g., `{figure} /path/to/image.png`).
+- Resolves image paths relative to the file or project root.
+- Handles image paths with optional titles (e.g., `"title"`) in Markdown and Notebook files.
+- Skips processing images that are already converted to the public URL.
+- Copies images to the `new_images` folder.
+- Updates the files to replace local image paths with public URLs.
+
+How to Use:
+1. Place this script in the root directory of your project (where `_toc.yml` is located).
+2. Ensure `_toc.yml` contains the list of files to process.
+3. Run the script using Python: python parse_images.py
+4. The script will:
+- Copy referenced images to the `new_images` folder.
+- Update the Markdown and Notebook files with the new image URLs.
+
+Dependencies:
+- Python 3.x
+- PyYAML (install using `pip install pyyaml`)
+
+Notes:
+- Ensure the script is run from the project root directory.
+- The `base_url` variable should be updated to match your desired public URL prefix.
+- The script handles image paths in the following formats:
+  - Relative paths (e.g., `image.png`, `./image.png`).
+  - Absolute paths (e.g., `/path/to/image.png`).
+  - Paths with optional titles (e.g., `![alt text](image.png "title")`).
+"""
+
+import os
+import re
+import shutil
+import yaml
+import json
+
+# Define the folder where images will be copied
+output_folder = "new_images"
+base_url = "https://files.mude.citg.tudelft.nl/"
+
+# Ensure the output folder exists
+os.makedirs(output_folder, exist_ok=True)
+
+# Function to parse the _toc.yml file and extract all Markdown and Notebook files
+def get_files_from_toc(toc_file):
+    files = []
+    with open(toc_file, "r", encoding="utf-8") as f:
+        toc = yaml.safe_load(f)
+
+        # Recursive function to extract file paths
+        def extract_files(item):
+            if isinstance(item, dict):
+                if "file" in item:
+                    # Add the file with the appropriate extension
+                    file_path = item["file"]
+                    if not file_path.endswith((".md", ".ipynb")):
+                        if os.path.isfile(file_path + ".md"):
+                            file_path += ".md"
+                        elif os.path.isfile(file_path + ".ipynb"):
+                            file_path += ".ipynb"
+                    files.append(file_path)
+                if "sections" in item:
+                    for section in item["sections"]:
+                        extract_files(section)
+                if "chapters" in item:
+                    for chapter in item["chapters"]:
+                        extract_files(chapter)
+            elif isinstance(item, list):
+                for sub_item in item:
+                    extract_files(sub_item)
+
+        # Start extracting files from the "parts" section
+        extract_files(toc.get("parts", []))
+    return files
+
+# Function to normalize image paths
+def normalize_image_path(file_dir, image_path):
+    # Check if the path starts with a `/` (absolute path relative to the project root)
+    if image_path.startswith("/"):
+        # Resolve the path relative to the project root
+        project_root = os.getcwd()  # Assuming the script is run from the project root
+        resolved_path = os.path.join(project_root, image_path.lstrip("/"))
+    else:
+        # Resolve the path relative to the file's directory
+        resolved_path = os.path.normpath(os.path.join(file_dir, image_path))
+    return resolved_path
+
+# Function to find and replace local image references
+def process_file(file_path):
+    if file_path.endswith(".md"):
+        process_markdown(file_path)
+    elif file_path.endswith(".ipynb"):
+        process_notebook(file_path)
+
+# Process Markdown files
+def process_markdown(file_path):
+    file_dir = os.path.dirname(file_path)  # Get the directory of the file
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Find all standard Markdown image references (e.g., ![alt text](path "title"))
+    matches = re.findall(r"!\[.*?\]\((.*?)(?:\s+\".*?\")?\)", content)
+    # Find all MyST figure syntax references (e.g., {figure} path)
+    # Handles cases where the `---` block is missing or caption follows directly
+    myst_matches = re.findall(r"\{figure\}\s+(.*?)\s*(?:\n|$)", content)
+    matches.extend(myst_matches)
+
+    for match in matches:
+        # Skip if the image path is already converted to the public URL
+        if match.startswith(base_url):
+            continue
+
+        # Normalize and resolve the image path
+        image_path = normalize_image_path(file_dir, match)
+
+        if os.path.isfile(image_path):
+            print(f"Image found: {image_path}")  # Debugging output
+            # Copy the image to the output folder
+            image_name = os.path.basename(image_path)
+            new_path = os.path.join(output_folder, image_name)
+            shutil.copy(image_path, new_path)
+
+            # Replace the local URL with the new URL
+            new_url = base_url + image_name
+            content = content.replace(match, new_url)
+        else:
+            print(f"Warning: Image not found: {image_path}")  # Debugging output
+
+    # Write the updated content back to the file
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+# Process Jupyter Notebook files
+def process_notebook(file_path):
+    file_dir = os.path.dirname(file_path)  # Get the directory of the file
+    with open(file_path, "r", encoding="utf-8") as f:
+        notebook = json.load(f)
+
+    updated = False
+    for cell in notebook.get("cells", []):
+        if cell.get("cell_type") == "markdown":
+            # Join all lines in the cell into a single string
+            cell_content = "".join(cell.get("source", []))
+
+            # Find all standard Markdown image references (e.g., ![alt text](path "title"))
+            matches = re.findall(r"!\[.*?\]\((.*?)(?:\s+\".*?\")?\)", cell_content)
+            # Find all MyST figure syntax references (e.g., {figure} path)
+            myst_matches = re.findall(r"\{figure\}\s+(.*?)\s*(?:\n|$)", cell_content)
+            matches.extend(myst_matches)
+
+            for match in matches:
+                # Skip if the image path is already converted to the public URL
+                if match.startswith(base_url):
+                    continue
+
+                # Normalize and resolve the image path
+                image_path = normalize_image_path(file_dir, match)
+
+                if os.path.isfile(image_path):
+                    print(f"Image found: {image_path}")  # Debugging output
+                    # Copy the image to the output folder
+                    image_name = os.path.basename(image_path)
+                    new_path = os.path.join(output_folder, image_name)
+                    shutil.copy(image_path, new_path)
+
+                    # Replace the local URL with the new URL
+                    new_url = base_url + image_name
+                    cell_content = cell_content.replace(match, new_url)
+                    updated = True
+                else:
+                    print(f"Warning: Image not found: {image_path}")  # Debugging output
+
+            # Split the updated content back into lines and update the cell
+            cell["source"] = cell_content.splitlines(keepends=True)
+
+    # Write the updated notebook back to the file if changes were made
+    if updated:
+        with open(file_path, "w", encoding="utf-8") as f:
+            json.dump(notebook, f, indent=2)
+
+# Main function
+def main():
+    toc_file = "_toc.yml"  # Replace with the path to your _toc.yml file
+    files = get_files_from_toc(toc_file)
+
+    print("Files extracted from TOC:", files)  # Debugging output
+
+    for file_path in files:
+        # Ensure the file has the correct extension and exists
+        if os.path.isfile(file_path):
+            print(f"Processing file: {file_path}")  # Debugging output
+            process_file(file_path)
+        else:
+            print(f"Warning: File {file_path} not found or unsupported.")
+
+if __name__ == "__main__":
+    main()

book/images/nothing.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"></svg>

book/images/sphinx-logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 7">
+<path d="M8.12 3.27c.45-.32 1.06-.46 1.78-.73l-.31-.7c-1.28.23-2.43-.53-3.68-.7C4 .75 2.24 1.9.36 2.04v.76c1.87.41 3.64 1.26 5.6 1.02-1.21 1.21-2.84 2.64-4.69 2.07C.63 5.77.35 4.87.96 4.6c.27 1.04 1.57.3 1-.52C1.57 3.6.54 3.82.24 4.3c-.87 1.65.84 2.56 2.31 2.32 1.86-.25 3.29-1.71 4.53-3.02-.02.61.18 1.96-.41 2.5l.01.9c.43-.34.8-1.07.92-1.56.16-.63.04-1.02.1-1.53.05-.23.1-.41.42-.64zM1.9 2.39c.77-.23 1.58-.58 2.39-.66-.42 1.38 1.81 1.54 1.56 0 .64.16 1 .3 1.94.7-2.06 1.02-4.05.56-5.89-.04z"/>
+<path d="M.36 1.81v-.8c.23 0 .84-.18 1.44-.35C2.8.36 4.05 0 4.95 0c1 0 2.05.34 2.82.58l.91.25c.62.07.98-.08.98-.08l.34.73c-.06.02-.56.24-1.41.15-.27-.03-.62-.14-1.06-.29C6.77 1.1 5.82.8 4.95.8c-.79 0-1.97.35-2.92.63-.74.21-1.32.38-1.67.38z"/>
+</svg>

book/installation-and-setup/anaconda.md

@@ -1,9 +1,11 @@
-# Managing code-related software: Anaconda
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This page is useful for user type 5.
 ```
+````
+
+# Managing code-related software: Anaconda
 
 Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. Unfortunately, each of these packages are themselves require a number of different packages to function properly. Do you like installing all of them? You shouldn't---but where do you get them come from? Many of those packages are packages required by only a few specific packages. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run install a specific package, `conda` (part of Anaconda) checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` (collection of software with a specific version) that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you use them to install a package. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly!
 
@@ -34,7 +36,7 @@ A python virtual environment is, like the name might suggest, a reserved space w
 
 ### Set-up environments
 
-Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book.
+Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a TeachBook.
 
 For simplicity we will call this environment `my_new_book_env`, but you can give it any name you like.
 
@@ -45,7 +47,7 @@ For simplicity we will call this environment `my_new_book_env`, but you can give
 
 4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section)
 
-Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
+Now everytime you want to work on your TeachBook, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
 
 As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `teachbooks` which is a wrapper around JupyterBooks. More information about this package [here](jupyter-book-setup.md).
 

book/installation-and-setup/collab.md

@@ -1,9 +1,11 @@
-# Organize editing team, collaboration and visibility
+````{margin}
-
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4-5.
 ```
+````
+
+# Organize editing team, collaboration and visibility
 
 ## Roles and responsibilities
 To ensure smooth collaboration, it is essential to define the roles and responsibilities within your team. Firstly, designate who will be in charge of team organization ('administrators') who should be at least user type 4. Additionally, assign 'maintainers' responsible for combining content, also requiring at least user type 4. 'Editors' should be identified for editing and reviewing content, requiring at least user type 3.
@@ -13,7 +15,7 @@ Finally, ensure that team members identify themselves according to the user type
 ## Review process
 Furthermore, establish a clear editing and review process.
 
-For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {fa}`fa-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised.
+For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {octicon}`mark-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/v1/basics/repository.html) is advised.
 
 (draft_book)=
 ## Define draft version of book
@@ -46,4 +48,4 @@ Additionally, it is advisable to document the branch protection strategy and the
 - Block force pushes
 
 ## Private, internally or public
-Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education.
+Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education.

book/installation-and-setup/copyright.md

@@ -1,12 +1,18 @@
-(copyright)=
+````{margin}
-# Copyright and Licenses checklist
+```{attributiongrey} Attribution
-
+:class: attribution
-> This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+```
 
 ```{admonition} User types
 :class: tip
 This page is useful for all user types.
 ```
+````
+
+(copyright)=
+# Copyright and Licenses checklist
+
 
 The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git.  Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft!
 

book/installation-and-setup/copyright/considerations.md

@@ -1,7 +1,14 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+```
+````
+
 (copyright_considerations)=
 # Copyright Considerations
 
-> This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+
 
 Copyright law dictates how online book material can and should be created, maintained and shared. An author should understand a few key concepts, as well as best practices, in order to create a book that not only is a useful resource, but, also fairly reuses the work of others and, if provided with an open license, enables original content to also be reused.
 
@@ -59,12 +66,6 @@ The use of open licenses actually does not prohibit the author from using the ma
 
 **Still don't agree?** Sorry. Please take this up with your nearest library or copyright expert and let us know if you get a different response! In the meantime, we will simply list ourselves as authors, use CC BY licenses and remember that TU Delft holds the copyright for our work produced as teachers.
 
-```{warning}
-The TeachBooks Team isn't sure where code and data lie here. Since TeachBooks is oriented towards education, we assume that TU Delft also owns the copyright for this.
-
-Do you have a better answer? Let us know!
-```
-
 ## Licensing
 
 This dictates how others may or may not be able to share or (re)use your work. It is (fortunately) becoming more common to include licenses with educational material (including books), which makes it much easier to understand how specific material can be used. Note that _in the absence of a license, you must assume that nothing can be reused!_ In this case you have to ask permission to the copyright holder, which can be a time-consuming process. License considerations are described in more detail in the following pages.
@@ -83,4 +84,4 @@ There are many legal aspects to consider when creating an online book. Hopefully
 2. Clearly **indicate where and how you have used the work of others** in your book (i.e., within the _content_ of your book).
 3. **Summarize all sources** used in your book, as well as what may or may not be included under the license which you have chosen.
 
-The following pages illustrate how to do this. It turns out to be not only a clear set of instructions for (re)users of your content, but also to help you remember what you have used in your book and where to find it later if changes are needed.
+The following pages illustrate how to do this. It turns out to be not only a clear set of instructions for (re)users of your content, but also to help you remember what you have used in your book and where to find it later if changes are needed.

book/installation-and-setup/copyright/licenses.md

@@ -1,8 +1,13 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+```
+````
+
 (copyright_licenses)=
 # Licenses
 
-> This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
-
 Here we present an overview of various license types, with a particular focus on the preference of TeachBooks to use Permissive Open Licenses, regardless of whether material is _content, code or data_ (described below). 
 
 ```{admonition} Why permissive open licenses?
@@ -11,7 +16,7 @@ Here we present an overview of various license types, with a particular focus on
 Since we (TeachBooks) authors have been working on making online books, we see the value in making content available for reuse. When preparing a new page or assignment, nothing makes us happier than seeing a CC BY license on something that we would like to (re)use ourselves. Why? Because we know that all we have to do is properly attribute the work and we can get on with our true passion: **teaching!**
 ```
 
-This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, Jupyter Books), which are composed of two parts:
+This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, TeachBooks), which are composed of two parts:
 1. An online document in the form of a website, accessible at a specific URL, and
 2. The _source code,_ which defines the _content_ and is required to create the website.