Merge pull request #78 from TeachBooks/pages_from_others

Pages from others

book/_toc.yml

@@ -14,6 +14,7 @@ parts:
       - file: exercises/003.md
       - file: exercises/004.md
       - file: exercises/005.md
+      - file: exercises/005a.md
       - file: exercises/006.md
       - file: exercises/summary
     - file: syntax_exercises.md

book/exercises.md

@@ -9,7 +9,8 @@ Maybe you're already comfortable with Git, GitHub and the concept of using softw
 3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
 4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
 5. Can you merge your branch into `main` with a pull request?
-6. Can you fork someone else's repo, and suggest a change in a pull request?
+6. Can you add read-only content from someone else without manually copying the source?
+7. Can you fork someone else's repo, and suggest a change in a pull request?
 
 If something is not clear, dive into to the relevant exercise page.
 ```

book/exercises/005a.md

@@ -0,0 +1,85 @@
+# 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?
+```
+
+
+
+
+
+
+
+
+
+
+
+

book/exercises/006.md

@@ -1,4 +1,4 @@
-# Exercise 6: Contribute to the book of somebody else
+# Exercise 7: Contribute to the book of somebody else
 
 ```{tip}
 For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner.

book/exercises/summary.md

@@ -15,10 +15,10 @@ Here is how these exercises relate to the workflow.
 | :---: | :---: | :---: | :---: |
 | 1 | Get and idea | 4 | Create an issue |
 | 2 | Create _your_ version of the book | 4 | Create a branch |
-| 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
-| 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary |
+| 3 | Edit the book | 1, 2, 3, 6| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
+| 4 | Check changes online | 1, 2, 3, 6 | Workflows and Actions Summary |
 | 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready|
-| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks |
+| 6 | Submit for review | 5, 7 | Open and merge a Pull Request, from a branch or forks |
 
 ## Keep practicing