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 to select and copy the link.

• If the page isn’t listed in the Recombiner, find the link manually in the GitHub repository.

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, 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).

     • Browse the files and find the .md page you want (e.g., README.md, workflows/collaboration.md).

     • Copy the raw link in this format:

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

Example

_toc.yml snippet:

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 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+F5to 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.

Fig. 2 Example of attribution box at the top of an external page.

Check your understanding

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?