Merge remote-tracking branch 'upstream/main'

README.md

@@ -1,7 +1,5 @@
 # Your first open interactive textbook using the GitHub template
 
-[![call-deploy-book](https://github.com/TUDelft-books/TUDelft-template/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TUDelft-books/TUDelft-template/actions/workflows/call-deploy-book.yml)
-
 > This page reuses CC BY 4.0 licensed content from https://github.com/TeachBooks/template.
 
 The template allows you to start your own open interactive textbook and hosting that textbook online without knowledge on Git, the Jupyter book package, python or anaconda. It doesn't elaborate on the collaborative functionalities of Git or how to edit the book. Please look at the TeachBooks manual (https://teachbooks.io/manual) to find more about that!

book/_config.yml

@@ -40,6 +40,7 @@ sphinx:
     - download_link_replacer
     - sphinx.ext.extlinks
     - sphinx_image_inverter
+    - sphinx_iframes
     - sphinx_exercise
     - sphinx_tudelft_theme
     - teachbooks_sphinx_tippy

book/_toc.yml

@@ -7,7 +7,7 @@ parts:
     - file: some_content/overview.md
       sections:
       - file: some_content/text_and_code.ipynb
-    - file: exercises
+    - file: exercises.md
       sections:
       - file: exercises/001.md
       - file: exercises/002.md
@@ -16,6 +16,10 @@ parts:
       - file: exercises/005.md
       - file: exercises/006.md
       - file: exercises/summary
+    - file: syntax_exercises.md
+      sections:
+      - file: syntax_exercises/007.md
+      - file: syntax_exercises/008.md
     - file: references.md
     - file: changelog.md
     - file: credits.md

book/changelog.md

@@ -1,4 +1,11 @@
 # Changelog
 
-## `<date>` [`<release name>`](<`link to release on GitHub>`)
+## `<latest version>`: `<date>`
 - `<Added/modified/deleted>` [](`<relative link to changed file>`)
+- ...
+- Full Changelog: `[<previous version>...<current version>](<link to diff as provided by GitHub>)`
+
+## `<previous version>`: <...>
+- <...>
+
+<...>

book/credits.md

@@ -3,11 +3,11 @@
 
 You can refer to this book as:
 
-> `<editors>` from Delft University of Technology (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`
+> `<editors>` from Delft University of Technology (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`. CC BY 4.0.
 
 You can refer to individual chapters or pages within this book as:
 
-> `<Title of Chapter or Page>`. In `<editors>` from Delft University of Technology (`<year>`) _`<title>`_. `<url to specific page on book website>`. Source files at `<link to specific commit / file in github repo`
+> `<Title of Chapter or Page>`. In `<editors>` from Delft University of Technology (`<year>`) _`<title>`_. `<url to specific page on book website>`. Source files at `<link to specific commit / file in github repo`. CC BY 4.0.
 
 We anticipate that the content of this book will change significantly. Therefore, we recommend using the source code directly with the citation above 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. However, we make no guarantee, so if it is important for you to reference a specific location/commit within the book.
 

book/exercises.md

@@ -1,4 +1,4 @@
-# Exercises
+# Exercises TeachBooks workflow
 
 > This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
 

book/exercises/001.md

@@ -1,3 +1,4 @@
+(exercise_1)=
 # Exercise 1: First file edit
 
 > This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
@@ -18,7 +19,7 @@ Can you add some content to the intro page?
 8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!).
 
 ````{hint} Watch the steps in action below
-:class: dropdown
+class: dropdown
 
 ```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true
 ---
@@ -26,14 +27,14 @@ name: template_demo_public
 ---
 Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco)
 ```
-
-
 ````
 
-:::{card} Check your understanding
-<iframe src="https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=2" width="624" height="324" frameborder="0" allowfullscreen="allowfullscreen" title="Testing your knowledge"></iframe><script src="https://home.teachbooks.io/wp-content/plugins/h5p/h5p-php-library/js/h5p-resizer.js" charset="UTF-8"></script>
-:::
+::::{card} Check your understanding
+```{h5p} https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=2
+```
+::::
 
-:::{card} Check your understanding
-<iframe src="https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=1" width="959" height="502" frameborder="0" allowfullscreen="allowfullscreen" title="Testing more Teachbooks knowledge"></iframe>
-:::
+::::{card} Check your understanding
+```{h5p} https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=1
+```
+::::

book/exercises/summary.md

@@ -2,7 +2,7 @@
 
 > This page reuses CC BY 4.0 licensed content from {cite:t}`template`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
 
-With the exercises, you did all the steps of our TeachBooks workflow!
+With the simple exercises, you did all the steps of our TeachBooks workflow!
 
 ```{figure} https://github.com/TeachBooks/logos_and_visualisations/blob/main/TB_flowchart/TeachBooks_flowchart.svg?raw=true
 ---
@@ -11,7 +11,7 @@ align: center
 ---
 ```
 
-Here is how the exercises relate to the workflow.
+Here is how these exercises relate to the workflow.
 
 | Step No. | Name | Exercise | Description |
 | :---: | :---: | :---: | :---: |
@@ -20,4 +20,9 @@ Here is how the exercises relate to the workflow.
 | 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
 | 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary |
 | 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready|
-| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks |
+| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks |
+
+## Keep practicing
+
+For additional practice, there are more exercises relating to the capacities of each user type. 
+Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are!

book/syntax_exercises.md

@@ -0,0 +1,7 @@
+# Syntax exercises
+
+The previous exercise guide you through making your own book following the TeachBooks workflow. Now lets get specific and dive into the possibilities of the syntax used!
+
+As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those!
+
+The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) which will come in handy!

book/syntax_exercises/007.md

@@ -0,0 +1,66 @@
+# Exercise 7: File structure by titles
+
+In this exercise you will learn how to structure your chapters.
+
+::::::{topic} Exercise objective
+Can you structure your page with a title and (sub)sections?
+::::::
+
+```{tip}
+
+More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html).
+
+```
+
+1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch. When you've arrived there, click `Add file` - {octicon}`plus;1em` `Create new file`.
+
+2. Name your file and end it with the file extension `.md` (e.g. `my_new_file.md`), your filename preferable shouldn't include spaces.
+
+3. Now let's create the structure of your chapter. You need to start with a title on the top of this page. The title is always defined in one of the first lines of the file after the hashtag `#`. So your file should look like:
+
+```md
+# Chapter title
+
+```
+
+4. Now let's add some more text and subsections as needed. You're only allowed to use one chapter title `#`, but there's no limit for the amount of sections, subsections, etc:
+
+```md
+# Chapter Title 
+text
+
+## Section Title 1
+text
+
+## Section Title 2
+text
+
+### Subsection Title 1
+text
+
+### Subsection Title 2
+text
+
+#### Heading 
+##### Smaller Heading
+###### Smallest Heading
+```
+
+5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
+
+6. Add a commit message.
+
+7. Now let's add your new file tot the table of contents, as explained in [](../exercises/002.md).
+
+8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? Soon, there'll be exercising on doing this locally which prevents you from waiting).
+
+9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Please not that the name of the page in the table of contents is identical to the title of the page, while the URL corresponds to the directory structure of the source files.
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on to the next exercise, make sure you understand the following:
+- What is the correct way to define a title in a Markdown file?
+- How many chapter titles (`#`) are allowed in a single Markdown file?
+- What file type are you using?
+```

book/syntax_exercises/008.md

@@ -0,0 +1,71 @@
+# Exercise 8: Add visual media
+
+To help you illustrate your content, it can be useful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale).
+
+::::::{topic} Exercise objective
+Can you add figures to your page?
+::::::
+
+```{note}
+Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows, especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned!).
+```
+
+
+1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file` -  {octicon}`upload;1em` `Upload new file`. Note that you can store your files in another folder within the book directory too. However it's good practice to store figures in a separate folder (eventually per chapter).
+
+2. Choose the visual media you want to upload. Remember its file name, including its file extension as you will need it later.
+
+3. Commit your changes.
+
+4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the same branch as where you've added your figure.
+
+5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/figures.html#figure-parameters)):
+
+````md
+```{figure} figures/<new_figure>.png
+---
+width: 80%
+align: center
+---
+<caption text>
+```
+````
+
+```{Warning}
+Make sure the file extension of your figure is correct because markdown differentiates capital letters!
+```
+
+```{Warning}
+If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folders above the current page>` )
+```
+
+6. To link and display an online figure, you can use the same `{figure}` directive. Just past in the :
+
+````md
+```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg
+---
+width: 80%
+align: center
+---
+<caption>
+```
+````
+
+6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
+
+7. Add a commit message.
+
+8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
+
+9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on to the next exercise, make sure you understand the following:
+- Where should you upload your visual media files in the repository?
+- What is the recommended practice for storing figures in the book directory?
+- What should you be cautious about when specifying the file extension of your figure?
+- How do you refer to a figure located in a different directory than your chapter?
+
+```

requirements.txt

@@ -6,7 +6,7 @@ download_link_replacer
 sphinx-exercise
 sphinx-tudelft-theme
 teachbooks-sphinx-tippy
+sphinx-iframes
 
-# now list the packages (and the respective url) you wish to download from the GitLab package registry
---extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
-sphinx-thebe ~= 0.9.9
+# Now list the packages you want to download directly from GitHub
+git+https://github.com/TeachBooks/Sphinx-Thebe