mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
85 lines
3.1 KiB
Markdown
85 lines
3.1 KiB
Markdown
# Exercise 6: Reuse content from another book
|
||
|
||
So far, you've been working inside your own book. But what if someone else has already written a page you’d like to reuse? Instead of copying it, you can **include it directly** into your own book using the `external:` feature in your `_toc.yml`.
|
||
|
||
You can find the link to reuse in one of two ways:
|
||
|
||
* Use the [TeachBooks Recombiner](https://teachbooks.io/recombiner/) to select and copy the link.
|
||
* If the page isn't listed in the Recombiner, find the link manually in the GitHub repository.
|
||
|
||
::::::{topic} Exercise objective
|
||
Can you include a page from someone else’s book into your own using `external:` in your `_toc.yml`?
|
||
::::::
|
||
|
||
|
||
1. Find the page you want to reuse:
|
||
|
||
* Option 1: Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/), select the book and chapter(s) you want to reuse, and click *Show how do it yourself instructions*. Copy the `external:` link provided.
|
||
* Option 2: If the page isn’t in the Recombiner, find it manually:
|
||
|
||
* Go to the repository (e.g., [TeachBooks Manual on GitHub](https://github.com/TeachBooks/manual)).
|
||
* Browse the files and find the `.md` page you want (e.g., `README.md`, `workflows/collaboration.md`).
|
||
* Copy the raw link in this format:
|
||
|
||
```yaml
|
||
- external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md
|
||
```
|
||
|
||
2. Add the `external:` link into `chapters:` section of your `_toc.yml` file.
|
||
|
||
3. Save the changes, commit, and push them.
|
||
|
||
|
||
````{admonition} Example
|
||
`_toc.yml` snippet:
|
||
|
||
```yaml
|
||
format: jb-book
|
||
root: intro
|
||
|
||
parts:
|
||
- caption: Contents
|
||
chapters:
|
||
- file: 001
|
||
- external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md
|
||
- file: 003
|
||
```
|
||
````
|
||
|
||
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 your changes, go to {octicon}`play` `Actions` - The most recent workflow run `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).
|
||
|
||
7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from.
|
||
|
||
```{figure} https://github.com/TeachBooks/template_figures/blob/main/external_page_attribution.png?raw=true
|
||
:name: external_page_attribution
|
||
:width: 100%
|
||
:alt: Example of attribution box shown at the top of an external page
|
||
|
||
Example of attribution box at the top of an external page.
|
||
```
|
||
|
||
```{admonition} Check your understanding
|
||
:class: note
|
||
|
||
Before moving on, make sure you understand:
|
||
|
||
* What is the benefit of linking to an external page instead of copying it?
|
||
* How does using the Recombiner simplify adding external content?
|
||
* What can you do if a page isn’t in the Recombiner?
|
||
```
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|