Textbook

Textbook#

We make use of an interactive online textbook to share content with students.Therefore, we make use of the TeachBooks platform, which is a spin-off of Jupyter Book.

Viewing the book#

  • Material is released to students when a commit is made to the 2025 branch at https://mude.citg.tudelft.nl/book/2025

  • Prior to sharing with students, material should be reviewed by making a commit to the 2025-draft branch. This can be viewed at https://mude.citg.tudelft.nl/book/2025-draft/.

  • All other branches are meant to be ‘in development’ and can be viewed on GitHub. Default is that the branch name is added after the root URL/repo_name. Actions page which summarizes all the branches and status: TUDelft-MUDE/book. As soon as the content is merged with the other content, these temporary branches are removed.

Editing the book#

Anyone with access can edit the book in the github repository: TUDelft-MUDE/book with the following steps:

  • Create a branch with your edits

  • Open a draft pull request and ask for feedback from fellow content experts / TAs / content coordinator / programming coordinator.

  • As soon as it ready, mark the pull request as ready and ask the content coordinator for a review (if you didn’t do that before)

  • The content coordinator will merge you pull request and delete your branch.

We identify a few user-types (taken from the TeachBooks Manual), pecifically for this MUDE-book:

  • User type 1/2: review by opening an issue by clicking the lightbulb on the top-right corner of a page.

  • User type 3/4/5: edit a file on a new branch and create a merge request to 2025-draft as described above

Depending on the type of user you want to be, you need to know only a few details or a bit more. If you’re completely new, go through the general introduction to these kind of books at platforms in the ‘Your first TeachBook!’ part of the TeachBooks Manual. If you already now the basic, go through relevant pages (indicated per user type per page) in the Getting going! part of the manual.

The yearly and draft branches are protected with a ruleset. This is requiring pull requests for the with 1 approval (which hare dismissed upon new commits), requiring conversation resolution before merging, merging without rebase and blocking force pushes while allowing bypass by organization admins and the MUDE MT.

Starting in the academic year 2025-2026, we apply ‘TeachBooks versioning with academic_year.additions.errata. This is coordinated by the content coordinator.

Exercises#

For exercises in the book, we’d like to use:

FTP storage#

Images and binary or big files should be stored on our FTP-server. More information is available here. If you add an image using MyST syntax, add the FTP link like this:

```{figure} https://files.mude.citg.tudelft.nl/<filename>
---
name: figure_label
---
caption
```

If you’d like to use the download link replacer to add a button to download custom files, add those files to the FTP-server too:

```{custom_download_link} https://files.mude.citg.tudelft.nl/<path to file>
:text: "Custom text"
:replace_default: "False"
```

Are you looking for any old images that were deleted? Take a look at the repository on the tag images_archive.

Attribution#

Attribution

Written by <author(s)>

For every chapter, a note on attribution is added to make clear who are the authors. Add this note on independent pages on full-width. For chapters with multiple pages: add the note to the main page of a chapter on top in the margin. On the bottom of each of the subpages, we add the same attribution, but on the full width:

```{attributiongrey} Attribution
:class: attribution
Written by <author(s)>
```

If the page is taken from another book, add the following:

````{margin}
```{attributiongrey} Attribution
:class: attribution
Written by <author(s)>

This page reuses CC BY content from {cite:t}`<reference in book/_bibliography/references.bib>`. {fa}`quote-left`[Find out more here](external_resources)
```
````

More information about these attribution blocks can be found in the TeachBooks manual

Permissions GitHub#

Permissions are managed with GitHub teams and organization roles:

  • Teacher and TAs are added to the ‘Content writers’ team with an all-repository write role.

  • The MUDE MT team has an all-repository admin role

If you don’t have access to this repository, request for it by asking Tom (programming coordinator). If you want to start straight away, fork the book instead of creating a fork.

A bit of history#

  • 2022-23: we made a Jupyter Book to archive of all material; students did not use an online book, only Brightspace

  • 2023-24: we made our first Jupyter Book, which used the draft-release workflow to release material

  • 2024-25: goal is to make the book open with a CC-BY license. GitHub (TeachBooks) is used to mirror the repo and facilitate a large number of draft versions of the book that can be used for review via the github actions workflow

  • 2025-26: all the book stuff is moved to GitHub to ease the deployment flow.

Contents