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. 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? ::::::

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).
In your own book repository, open the _toc.yml file. This controls which pages are shown in your book and in what order.
To use the functionality, use the external: keyword in the _toc.yml file to include a file directly from the GitHub repository as follows:

format: jb-book
root: .

parts:
  - caption: ...
    chapters:
    - file: ...
    .
    .
    .
    - external: <link to GitHub / GitLab source .md or .ipynb file>
    .
    .
    .

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

Commit your changes and push them to your GitHub repository.
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.
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

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!

: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?

3.2 KiB Raw Blame History Unescape Escape

Exercise 6: Use pages from someone else's book

3.2 KiB

Raw Blame History