diff --git a/book/syntax_exercises/009.md b/book/syntax_exercises/009.md index 6f8e9ef..64883c8 100644 --- a/book/syntax_exercises/009.md +++ b/book/syntax_exercises/009.md @@ -10,10 +10,10 @@ Can you create internal references to other sections, equations, tables, figures Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/references.html). ``` -## 1. Referencing a Chapter or Section +## Referencing a Chapter or Section -1. Open the Markdown file where you want to add a reference. -2. Lets start with the simplest way to create a reference to another chapter or section. This is by directly linking it through the file path as shown in the following syntax: +1. Open a new or existing Markdown file where you want to add a reference. +2. Let's start with the simplest way to create a reference to another chapter. Try this out by directly linking the chapter through the file path as shown in the following syntax. ```md [Text to display](path/to/file.md) @@ -35,7 +35,13 @@ If you leave the text part empty, the title of the chapter you're referring to w If the chapter you're referring to is in different directory than your chapter, you'll need to refer it using relative parts. If the to be referenced chapter is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `/.md`). If the to be referenced chapter is in another directory, move upwards with `../` (e.g. `../..//` ) ``` -3. Try out another way of referencing by using a target header. Navigate to the chapter or section you want to reference and assign it an identifier using `{ref}` as shown in the example below. +3. If we want to refer to a section within the same file, we can use local refencing by directly inputting the name of the required section. Use the example below to test this out. This code gives: [Jump to the next section](#referencing-an-equation) + +```md +[Jump to the next section](#referencing-an-equation) +``` + +4. Try out another way of referencing by using a target header. Navigate to the chapter or section you want to reference and assign it an identifier within brackets as shown in the example below. This could be once again in the same markdown file, or a different file in the same repository. ```md (exercise_1)= @@ -43,116 +49,124 @@ If the chapter you're referring to is in different directory than your chapter, Let's start with the most basic edit: add some text to a file and see that the website is updated... ``` -4. Now, lets explore three different ways to reference this section! For the first method, we use the standard title text by calling the identifier as follows: +5. Now, let's explore three different ways to reference this section or chapter! For the first method, we use the standard title text by calling the identifier as follows. This will display: My favourite exercise was {ref}`exercise_1`. ```md My favourite exercise was {ref}`exercise_1`. ``` - This will display: My favourite exercise was {ref}`exercise_1`. -5. For the second method, we want to refer to the section using a custom title text. Try this out by placing the text that you want to be displayed within the `` and calling the identifier within the <> as follows: + +6. For the second method, we want to refer to the section using a custom title text. Try this out by placing the text that you want to be displayed within `` and calling the identifier within <>. +This will display: My favourite exercise was {ref}`the first one `. ```md My favourite exercise was {ref}`the first one `. ``` - This will display: My favourite exercise was {ref}`the first one `. -6. The final method uses markdown syntax to also display a custom title text. Refer to the desired section once again, this time by putting the custom text within the [] and calling the identifier within the <> as shown below: + +7. The last method uses markdown syntax to also display a custom title text. Refer to the desired section once again, this time by putting the custom text within [] and calling the identifier within <> as shown below. This will display: My favourite exercise was [this one](exercise_1). ```md My favourite exercise was [this one](exercise_1). ``` - This will display: My favourite exercise was [this one](exercise_1). -These three referencing methods can also be used for referencing equations, tables and figures. -## 2. Referencing an Equation +## Referencing an Equation -To reference an equation, you need to define a label when creating the equation and refer to it elsewhere in your text using `{eq}`: +8. Now we will test our knowledge using an equation. Similar to the code below, create an equation using $$ and identify it using a label within the brackets. + + + ```md + + $$ F = m \cdot a$$ (eq:Newton) + + ``` + + $$ F = m \cdot a$$ (eq:Newton) + +9. Refer to this equation by using `{eq}` and calling the identifier within the `` to achieve: Refer to Equation {eq}`eq:Newton`. ```md - - ```{math} - :label: eq-example - E = mc^2 - ``` - -``` - -You can then reference this equation using: - -```md -Equation {eq}`eq-example` +Refer to Equation {eq}`eq:Newton` ``` +## Referencing a Table -## 3. Referencing a Table +10. Similar methods can also be used to refer to a table. Start by creating a table by copying the code below. The identifier is defined using `:name:`. -To reference a table, assign a label when defining it: + ````md + ```{table} Example Table + :name: tab-example + | Column 1 | Column 2 | + |----------|----------| + | A | B | + ``` + ```` -```md - ```{table} Example Table - :label: tab-example - | Column 1 | Column 2 | - |----------|----------| - | A | B | - ``` + +```{table} Example Table +:name: tab-example +| Column 1 | Column 2 | +|----------|----------| +| A | B | ``` -And refer to it using `{numref}`: +11. Refer to the table like {numref}`Table {number} ` using `{numref}` and `{number}` as follows: + ```md -Table {numref}`tab-example` +{numref}`Table {number} ` ``` + -## 4. Referencing a Figure +## Referencing a Figure -To reference a figure, label it when inserting it: +12. This can also be done for a figure. Let's add a figure as we learnt to do in [Exercise 8](008.md), but this time adding an identifier using `name:`. + + ````md + ```{figure} figures/example.png + --- + width: 80% + align: center + name: fig-example + --- + Example figure. + ``` + ```` + + +13. Refer to the figure in the format {numref}`Figure {number} ` using `{numref}` as follows: ```md - ```{figure} figures/example.png - --- - width: 80% - align: center - name: fig-example - --- - Example figure. - ``` +{numref}`Figure {number} ` ``` -And refer to it using `{numref}`: +## Referencing a Link + +14. Finally, let's reference a link, using the following syntax: ```md -Figure {numref}`fig-example` +[Text to display](url) ``` +For example, you can use the code below to display: Here is the [link to the template](https://teachbooks.github.io/template/). -## 5. Referencing a Link - -To reference a link, use the following syntax: - -```md -[Text to display](https://teachbooks.github.io/template/) -``` -For example, you can write: ```md Here is the [link to the template](https://teachbooks.github.io/template/). ``` -This wil display: Here is the [link to the template](https://teachbooks.github.io/template/). +15. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +16. Add a commit message. +17. 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). -## 6. Commit Your Changes +18. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -1. Once you have added your references, commit your changes to the repository. -2. Click the green `Commit changes` button. -3. Add a commit message. -4. View your changes using the `Actions` tab and check if they appear correctly. ```{admonition} Check your understanding :class: note