mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
73 lines
3.2 KiB
Markdown
73 lines
3.2 KiB
Markdown
# Exercise 6: Use pages from someone else's book
|
||
|
||
So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically!
|
||
|
||
\::::::{topic} Exercise objective
|
||
Can you include a page from someone else’s book into your own using the `external` keyword?
|
||
\::::::
|
||
|
||
1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`).
|
||
2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order.
|
||
3. To use the functionality, use the `external:` keyword in the `_toc.yml` file to include a file directly from the GitHub repository as follows:
|
||
|
||
```yaml
|
||
format: jb-book
|
||
root: .
|
||
|
||
parts:
|
||
- caption: ...
|
||
chapters:
|
||
- file: ...
|
||
.
|
||
.
|
||
.
|
||
- external: <link to GitHub / GitLab source .md or .ipynb file>
|
||
.
|
||
.
|
||
.
|
||
```
|
||
|
||
4. Try out different kind of links. You can point to:
|
||
* A file on a branch (this pulls the most recent version on that branch): `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md`
|
||
* A file at a specific commit (this takes the file during the state of a specific commit (06d67e8)): `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md`
|
||
* A file from a tag (this locks the file to the version associated with a specific tag (v1.1.1)): `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md`
|
||
|
||
|
||
5. Commit your changes and push them to your GitHub repository.
|
||
6. Open the book online (e.g. via GitHub Pages or the link in your repository's `Actions` > latest deploy) and check whether the external page appears correctly.
|
||
7. If the external page doesn't load or gives an error, double-check:
|
||
|
||
* The link is a raw `.md` file on GitHub (not the preview or rendered page).
|
||
* You’ve committed and pushed the `_toc.yml` change.
|
||
|
||
|
||
\`\`\`{admonition} Example `_toc.yml` snippet
|
||
|
||
```yaml
|
||
format: jb-book
|
||
root: intro
|
||
|
||
chapters:
|
||
- file: 001
|
||
- file: 002
|
||
- external:
|
||
url: https://github.com/teachbooks-demos/book-collaboration/blob/main/004.md
|
||
title: Collaboration in GitHub
|
||
- file: 003
|
||
```
|
||
|
||
````
|
||
|
||
```{tip}
|
||
You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book!
|
||
````
|
||
|
||
```{admonition} Check your understanding
|
||
:class: note
|
||
|
||
Before moving on, make sure you understand the following:
|
||
- What is the difference between linking to an external page vs copying it into your own book?
|
||
- How do you use the `external:` keyword in `_toc.yml`?
|
||
- Why might it be useful to include a page from another book instead of rewriting it yourself?
|
||
- How can you make sure an external page link works properly?
|
||
```
|