From e42fd30d764374649fa29da0559b13cdead44606 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:24:34 +0200 Subject: [PATCH] Update 005a.md --- book/exercises/005a.md | 93 +++++++++++------------------------------- 1 file changed, 24 insertions(+), 69 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index d75e2f0..9e49aa2 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -1,29 +1,33 @@ # 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 [TeachBooks Recombiner](https://teachbooks.io/recombiner/). +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 the Recombiner? +Can you include a page from someone else’s book into your own using `external:` in your `_toc.yml`? \:::::: -1. Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). -2. Select the book and chapter(s) you want to reuse: +1. **Find the page you want to reuse:** - * Click on the book (e.g., **TeachBooks Manual**). - * Browse the chapters and click the `+` button to select the ones you want (e.g., **Collaboration in GitHub**). -3. Click **Show how do it yourself instructions** -4. Follow the instructions provided: + * **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: - * Copy the external link (it will look something like this): + * 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/v1.1.1/book/workflows/collaboration.md - ``` - * Paste it into the `parts:` or `chapters:` section of your `_toc.yml` file in your book repository. - * Save the changes, commit, and push them. + ```yaml + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + ``` + +2. Add the `external:` link into the `parts:` or `chapters:` section of your `_toc.yml` file. + +3. Save the changes, commit, and push them. \::::::{admonition} Example: `_toc.yml` snippet @@ -33,19 +37,19 @@ root: intro chapters: - file: 001 - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/workflows/collaboration.md + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md - file: 003 ``` \:::::: -5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -6. Add a commit message. +5. Add a commit message. -7. To see your changes, go to {octicon}`play` `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. To see your changes, go to {octicon}`play` `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). -8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. @@ -56,54 +60,5 @@ 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? \:::::: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -