diff --git a/book/_toc.yml b/book/_toc.yml index 29d5ac6..954403c 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -16,16 +16,11 @@ parts: - file: exercises/005.md - file: exercises/006.md - file: exercises/summary - - file: exercises/advanced_exercises.md + - file: exercises/syntax_exercises.md sections: - - file: exercises/type3.md - sections: - - file: exercises/007.md - - file: exercises/008.md - - file: exercises/type4.md - sections: - - file: exercises/009.md - - file: exercises/010.md + - file: syntax_exercises/007.md + - file: syntax_exercises/008.md + - file: syntax_exercises/009.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/exercises/exercises.md b/book/exercises.md similarity index 97% rename from book/exercises/exercises.md rename to book/exercises.md index e885fe5..491c7a4 100644 --- a/book/exercises/exercises.md +++ b/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). diff --git a/book/exercises/007.md b/book/exercises/007.md deleted file mode 100644 index e16dbf7..0000000 --- a/book/exercises/007.md +++ /dev/null @@ -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. diff --git a/book/exercises/010.md b/book/exercises/010.md deleted file mode 100644 index 05bbfde..0000000 --- a/book/exercises/010.md +++ /dev/null @@ -1,6 +0,0 @@ -# Exercise 10: ... - -```{attention} - -Under Construction -``` \ No newline at end of file diff --git a/book/exercises/advanced_exercises.md b/book/exercises/advanced_exercises.md deleted file mode 100644 index e56629f..0000000 --- a/book/exercises/advanced_exercises.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/book/exercises/type3.md b/book/exercises/type3.md deleted file mode 100644 index c221588..0000000 --- a/book/exercises/type3.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/book/exercises/type4.md b/book/exercises/type4.md deleted file mode 100644 index 9986582..0000000 --- a/book/exercises/type4.md +++ /dev/null @@ -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) diff --git a/book/syntax_exercises.md b/book/syntax_exercises.md new file mode 100644 index 0000000..5c7c975 --- /dev/null +++ b/book/syntax_exercises.md @@ -0,0 +1,5 @@ +# 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! \ No newline at end of file diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md new file mode 100644 index 0000000..6fe0ddb --- /dev/null +++ b/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`. + +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? +``` \ No newline at end of file diff --git a/book/exercises/008.md b/book/syntax_exercises/008.md similarity index 57% rename from book/exercises/008.md rename to book/syntax_exercises/008.md index 8e7c72d..76806c8 100644 --- a/book/exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,60 +1,62 @@ # 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). +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! +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`. +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 as you will need it later. +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 correct branch. +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. +5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/syntax/images_and_figures.html#block-level-images)): +````md +```{figure} figures/.png +:width: 80% +:align: center - ```{figure} figures/.PNG - --- - width: 80% - align: center - name: my_new_figure - --- - - ``` - + +``` +```` ```{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/
.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/
` ) +``` + +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 + + +``` +```` + 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)) +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. -```` -````{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 - --- - - ``` -```` -````` diff --git a/book/exercises/009.md b/book/syntax_exercises/009.md similarity index 100% rename from book/exercises/009.md rename to book/syntax_exercises/009.md