Merge pull request #56 from TeachBooks/43-convert-exercises-from-freek

43 convert exercises from freek

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/exercises.md

@@ -1,4 +1,4 @@
-# Exercises
+# Exercises TeachBooks workflow
 
 Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. We welcome you to work through the exercises attached to this page (you can find them in the left sidebar).
 

book/exercises/001.md

@@ -1,3 +1,4 @@
+(exercise_1)=
 # Exercise 1: First file edit
 
 Let's start with the most basic edit: add some text to a file and see that the website is updated.

book/exercises/summary.md

@@ -1,6 +1,6 @@
 # Summary of exercises: All Exercises
 
-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
 ---
@@ -9,7 +9,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 |
 | :---: | :---: | :---: | :---: |
@@ -18,4 +18,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 (Markdown)
+
+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.
+
+```{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?
+
+```