admin2/template
1
0
Fork 0
mirror of https://github.com/TeachBooks/template.git synced 2026-11-13 14:45:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Edits TOm

Browse source
This commit is contained in:
Tom van Woudenberg 2025-03-04 07:50:01 +01:00
parent 97a8274eb0
commit 0bdb1d31a1
11 changed files with 109 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

32
book/exercises/007.md
View file

@ -1,32 +0,0 @@
# Exercise 7: File Structure (Markdown)
In this exercise you will learn how to structure your chapters.
```{tip}
More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html).
```
1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch.
2. Let's create the structure of your chapter. You can start by adding a title to the section. The title is always defined in the first line of the file after the hashtag `#`. Then you can also add sections and subsections as needed.
```
# Chapter Title
## Section Title
### Subsection Title
#### Heading
##### Smaller Heading
###### Smallest Heading
```
3. Add some text to the (sub)sections to complete your chapter.
4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
5. Add a commit message.
6. 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 (user type 4))
7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.

60
book/exercises/008.md
View file

@ -1,60 +0,0 @@
# Exercise 8: Add visual media
To help you illustrate your content, it can be sueful 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).
```{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!
```
`````{tab-set}
````{tab-item} Embedding
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 > Upload new file`.
2. Choose the visual media you want to upload. Remember its file name 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 correct branch.
5. Copy this syntax and adjust the file name, width, alignment and caption.
```{figure} figures/<new_figure>.PNG
---
width: 80%
align: center
name: my_new_figure
---
<caption>
```
```{Warning}
Make sure the file extension of your figure is correct because markdown differentiates capital letters!
```
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 (user type 4))
9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
````
````{tab-item} Linking
To link and display an online figure, you can use the `{figure}` directive, which also allows captions and references.
```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg
---
width: 80%
align: center
name: my_linked_figure
---
<caption>
```
````
`````

45
book/exercises/009.md
View file

@ -1,45 +0,0 @@
# Exercise 9: Referencing using target headers
It can be really useful to refer to a specific section in your book while working in a different file. Referencing can be done using target headers such as:
```
(<title>)=
```
1. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the correct branch.
2. Identify the section you want to reference and name it between brackets for example `exercise_1`.
```
(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...
```
3. There are three types of referencing:
* You can use the standard title text which will be the title after the target header
My favourite exercise was {ref}`exercise_1`.
```
My favourite exercise was {ref}`exercise_1`.
```
* You can also specify the title text of the target header (aka specify what the link will say):
My favourite exercise was {ref}`the first one <exercise_1>`.
```
My favourite exercise was {ref}`the first one <exercise_1>`.
```
* You can also use Markdown syntax, then the title text is also fully customizable.
My favourite exercise was [this one](exercise_1).
```
My favourite exercise was [this one](exercise_1).
```

6
book/exercises/010.md
View file

@ -1,6 +0,0 @@
# Exercise 10: ...
```{attention}
Under Construction
```

5
book/exercises/advanced_exercises.md
View file

@ -1,5 +0,0 @@
# Advanced exercises
The previous exercise guide you through making your own book. Now lets get specific!
This chapter includes a couple of more exercises directed to the different user types.

15
book/exercises/exercises.md
View file

@ -1,15 +0,0 @@
# Exercises
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).
```{tip}
Maybe you're already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents. In that case, can you answer the following questions (referring to the exercises):
1. Can you add some content to the intro page?
2. Can you add the file named `file_to_be_added_to_toc.md` to the book website?
3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
5. Can you merge your branch into `main` with a pull request?
6. Can you fork someone else's repo, and suggest a change in a pull request?
If something is not clear, dive into to the relevant exercise page.
```

8
book/exercises/type3.md
View file

@ -1,8 +0,0 @@
# User Type 3
Now that you've made your own version of the book, it's time to add some content. 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. In this exercise you will learn how to structure a `.md` file.
Exercises for user type 3 relate to:
- [File structure (Markdown)](007.md)
- [Adding visual media](008.md)

7
book/exercises/type4.md
View file

@ -1,7 +0,0 @@
# User type 4
User 4 is a hybrid between type 3 and 5. As user type 4 you will mainly be making changes by editing the `.md` files locally using, for example, VS Code.
Exercises for user type 4 relate to:
- [Referencing](009.md)