From 4dda1b0e95e93ba05e01bd3213cb82cfae8003ba Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:20:57 +0200 Subject: [PATCH 01/18] exercise 6 --- book/exercises/006.md | 112 +++++++++++++++++++++++++----------------- book/exercises/007.md | 53 ++++++++++++++++++++ 2 files changed, 119 insertions(+), 46 deletions(-) create mode 100644 book/exercises/007.md diff --git a/book/exercises/006.md b/book/exercises/006.md index 9287d06..3dda89f 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -1,53 +1,73 @@ -# Exercise 6: Contribute to the book of somebody else +# 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: + . + . + . +``` + +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} -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. -``` - -So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. - -```{note} -The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. -``` - -::::::{topic} Exercise objective -Can you fork a book repository of someone else, make changes and contribute back? -:::::: - -```{tip} -This part describes how you can make a change in the book of someone else. -``` - -1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). -2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. -3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` -4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ -5. Check the changes in the online book. -6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. -7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. -8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. -9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. -10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! - -```{tip} -This part describes how you can accept the changes in your book made by someone else. -``` - -1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. -2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? -3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. -4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. -5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. - -Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. +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 a fork and how does it differ from a branch? -- Why is it important to create an issue before starting to work on a contribution? -- How do you create a pull request from a forked repository to the original repository? -- What should you include in the description of a pull request? -- How can you ensure that your friend is aware of your pull request? -``` \ No newline at end of file +- 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? +``` diff --git a/book/exercises/007.md b/book/exercises/007.md new file mode 100644 index 0000000..94d9635 --- /dev/null +++ b/book/exercises/007.md @@ -0,0 +1,53 @@ +# 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. +``` + +So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. + +```{note} +The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. +``` + +::::::{topic} Exercise objective +Can you fork a book repository of someone else, make changes and contribute back? +:::::: + +```{tip} +This part describes how you can make a change in the book of someone else. +``` + +1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` +4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ +5. Check the changes in the online book. +6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. +7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. +8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. +9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. +10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! + +```{tip} +This part describes how you can accept the changes in your book made by someone else. +``` + +1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. +2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? +3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. +4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. +5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. + +Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand the following: +- What is a fork and how does it differ from a branch? +- Why is it important to create an issue before starting to work on a contribution? +- How do you create a pull request from a forked repository to the original repository? +- What should you include in the description of a pull request? +- How can you ensure that your friend is aware of your pull request? +``` \ No newline at end of file From 8808d2ff0957913be6e4cd40c7f04451d185948d Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:24:23 +0200 Subject: [PATCH 02/18] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index 23ac43c..19b9103 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -15,6 +15,7 @@ parts: - file: exercises/004.md - file: exercises/005.md - file: exercises/006.md + - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: From 7478b4ccf843418971551c2fd6de32376d1633e7 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:28:22 +0200 Subject: [PATCH 03/18] Update 006.md --- book/exercises/006.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/exercises/006.md b/book/exercises/006.md index 3dda89f..658738c 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -2,9 +2,9 @@ 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 +::::::{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. @@ -41,7 +41,7 @@ parts: * You’ve committed and pushed the `_toc.yml` change. -\`\`\`{admonition} Example `_toc.yml` snippet +````{admonition} Example `_toc.yml` snippet ```yaml format: jb-book @@ -60,7 +60,7 @@ chapters: ```{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 From 6d0eff1bc0f04ba7e37d12b860b22690770065a1 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:37:45 +0200 Subject: [PATCH 04/18] Update 006.md --- book/exercises/006.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/exercises/006.md b/book/exercises/006.md index 658738c..1486188 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -41,8 +41,7 @@ parts: * You’ve committed and pushed the `_toc.yml` change. -````{admonition} Example `_toc.yml` snippet - +````{admonition} Example: TOC snippet ```yaml format: jb-book root: intro @@ -55,7 +54,6 @@ chapters: title: Collaboration in GitHub - file: 003 ``` - ```` ```{tip} From bada7e161c5e3d2a09a3a9a6c15602f5bd37b0bf Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 13 May 2025 10:48:59 +0200 Subject: [PATCH 05/18] restructure a bit Keep original urls --- book/_toc.yml | 2 +- book/exercises.md | 3 +- book/exercises/005a.md | 71 +++++++++++++++++++++++++ book/exercises/006.md | 108 ++++++++++++++++---------------------- book/exercises/007.md | 53 ------------------- book/exercises/summary.md | 6 +-- 6 files changed, 122 insertions(+), 121 deletions(-) create mode 100644 book/exercises/005a.md delete mode 100644 book/exercises/007.md diff --git a/book/_toc.yml b/book/_toc.yml index 19b9103..abecdbf 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -14,8 +14,8 @@ parts: - file: exercises/003.md - file: exercises/004.md - file: exercises/005.md + - file: exercises/005a.md - file: exercises/006.md - - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: diff --git a/book/exercises.md b/book/exercises.md index 491c7a4..cca212a 100644 --- a/book/exercises.md +++ b/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. ``` diff --git a/book/exercises/005a.md b/book/exercises/005a.md new file mode 100644 index 0000000..1486188 --- /dev/null +++ b/book/exercises/005a.md @@ -0,0 +1,71 @@ +# 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: + . + . + . +``` + +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 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? +``` diff --git a/book/exercises/006.md b/book/exercises/006.md index 1486188..94d9635 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -1,71 +1,53 @@ -# 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: - . - . - . -``` - -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 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 -``` -```` +# Exercise 7: Contribute to the book of somebody else ```{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! +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. ``` +So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. + +```{note} +The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. +``` + +::::::{topic} Exercise objective +Can you fork a book repository of someone else, make changes and contribute back? +:::::: + +```{tip} +This part describes how you can make a change in the book of someone else. +``` + +1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` +4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ +5. Check the changes in the online book. +6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. +7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. +8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. +9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. +10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! + +```{tip} +This part describes how you can accept the changes in your book made by someone else. +``` + +1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. +2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? +3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. +4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. +5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. + +Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. + ```{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? -``` +- What is a fork and how does it differ from a branch? +- Why is it important to create an issue before starting to work on a contribution? +- How do you create a pull request from a forked repository to the original repository? +- What should you include in the description of a pull request? +- How can you ensure that your friend is aware of your pull request? +``` \ No newline at end of file diff --git a/book/exercises/007.md b/book/exercises/007.md deleted file mode 100644 index 94d9635..0000000 --- a/book/exercises/007.md +++ /dev/null @@ -1,53 +0,0 @@ -# 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. -``` - -So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. - -```{note} -The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. -``` - -::::::{topic} Exercise objective -Can you fork a book repository of someone else, make changes and contribute back? -:::::: - -```{tip} -This part describes how you can make a change in the book of someone else. -``` - -1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). -2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. -3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` -4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ -5. Check the changes in the online book. -6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. -7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. -8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. -9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. -10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! - -```{tip} -This part describes how you can accept the changes in your book made by someone else. -``` - -1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. -2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? -3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. -4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. -5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. - -Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. - -```{admonition} Check your understanding -:class: note - -Before moving on, make sure you understand the following: -- What is a fork and how does it differ from a branch? -- Why is it important to create an issue before starting to work on a contribution? -- How do you create a pull request from a forked repository to the original repository? -- What should you include in the description of a pull request? -- How can you ensure that your friend is aware of your pull request? -``` \ No newline at end of file diff --git a/book/exercises/summary.md b/book/exercises/summary.md index 25bc7d6..a166a9d 100644 --- a/book/exercises/summary.md +++ b/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 From 0439c883b8f10844200cb749fd4a10e6475df7d7 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 17:20:12 +0200 Subject: [PATCH 06/18] Update 005a.md --- book/exercises/005a.md | 146 ++++++++++++++++++++++++++--------------- 1 file changed, 92 insertions(+), 54 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 1486188..d75e2f0 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -1,71 +1,109 @@ -# Exercise 6: Use pages from someone else's book +# 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 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: - . - . - . -``` - -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` +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/). -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. +\::::::{topic} Exercise objective +Can you include a page from someone else’s book into your own using the Recombiner? +\:::::: -````{admonition} Example: TOC snippet +1. Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). +2. Select the book and chapter(s) 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: + + * Copy the external link (it will look something like this): + + ```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. + +\::::::{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 + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/workflows/collaboration.md - 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! -``` +\:::::: + +5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +6. 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). + +8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the 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? + \:::::: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -```{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? -``` 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 07/18] 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? \:::::: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - From 087f66fe61959f0afd67db9d2701fc5c1219bf31 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:31:20 +0200 Subject: [PATCH 08/18] display updates --- book/exercises/005a.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 9e49aa2..684e4b4 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -7,19 +7,19 @@ 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 +::::::{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:** +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: + * 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: + * Copy the raw link in this format: ```yaml - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md @@ -29,7 +29,7 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -\::::::{admonition} Example: `_toc.yml` snippet +````{admonition} Example: `_toc.yml` snippet ```yaml format: jb-book @@ -41,7 +41,7 @@ chapters: - file: 003 ``` -\:::::: +```` 4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. @@ -53,12 +53,12 @@ chapters: -\::::::{admonition} Check your understanding -\:class: note +```{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? - \:::::: +``` From 024ae261a63d86cf4aa7b83d35906269c43d1b33 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:38:34 +0200 Subject: [PATCH 09/18] display updates 2 --- book/exercises/005a.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 684e4b4..6a21222 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -29,7 +29,7 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -````{admonition} Example: `_toc.yml` snippet +```{admonition} Example: `_toc.yml` snippet ```yaml format: jb-book @@ -41,7 +41,7 @@ chapters: - file: 003 ``` -```` +``` 4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. @@ -62,3 +62,15 @@ Before moving on, make sure you understand: * How does using the Recombiner simplify adding external content? * What can you do if a page isn’t in the Recombiner? ``` + + + + + + + + + + + + From 76658764fa414e62d2b26d2f71d390d260b04a6e Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:42:53 +0200 Subject: [PATCH 10/18] display updates 3 --- book/exercises/005a.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 6a21222..588b0f2 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -29,19 +29,19 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -```{admonition} Example: `_toc.yml` snippet -```yaml -format: jb-book -root: intro +````{admonition} Example: `_toc.yml` snippet -chapters: - - file: 001 - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md - - file: 003 -``` + ```yaml + format: jb-book + root: intro -``` + chapters: + - file: 001 + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/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. From 1950fb6df2b8756cd1d03a5ebc212f0a51772199 Mon Sep 17 00:00:00 2001 From: katiagatt <168722303+katiagatt@users.noreply.github.com> Date: Mon, 2 Jun 2025 22:47:12 +0200 Subject: [PATCH 11/18] display updates 4 --- book/exercises/005a.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 588b0f2..355e9e2 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -30,7 +30,8 @@ Can you include a page from someone else’s book into your own using `external: 3. Save the changes, commit, and push them. -````{admonition} Example: `_toc.yml` snippet +````{admonition} Example + `_toc.yml` snippet: ```yaml format: jb-book From b5436bd8ff62b388e66be4342d30809511ed55ed Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 12 Jun 2025 12:56:48 +0200 Subject: [PATCH 12/18] external link with branch --- book/exercises/005a.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 355e9e2..06dcb19 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -22,7 +22,7 @@ Can you include a page from someone else’s book into your own using `external: * Copy the raw link in this format: ```yaml - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md ``` 2. Add the `external:` link into the `parts:` or `chapters:` section of your `_toc.yml` file. @@ -39,7 +39,7 @@ Can you include a page from someone else’s book into your own using `external: chapters: - file: 001 - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/book_structure.md + - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md - file: 003 ``` ```` From 0f6ba3dc46fe97e04ca190d07f348ac2da43dfec Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 17 Jun 2025 18:49:18 +0200 Subject: [PATCH 13/18] external page test --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index abecdbf..ffebe94 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -17,6 +17,7 @@ parts: - file: exercises/005a.md - file: exercises/006.md - file: exercises/summary + - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/overview.md - file: syntax_exercises.md sections: - file: syntax_exercises/007.md From f9111b4916aa786e03f26df0a508d6406dc78506 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 17 Jun 2025 19:54:03 +0200 Subject: [PATCH 14/18] new step --- book/_toc.yml | 1 - book/exercises/005a.md | 8 ++++++++ book/figures/external_page_attribution.png | Bin 0 -> 6996 bytes 3 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 book/figures/external_page_attribution.png diff --git a/book/_toc.yml b/book/_toc.yml index ffebe94..abecdbf 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -17,7 +17,6 @@ parts: - file: exercises/005a.md - file: exercises/006.md - file: exercises/summary - - external: https://github.com/TeachBooks/manual/blob/v1.1.1/book/examples/overview.md - file: syntax_exercises.md sections: - file: syntax_exercises/007.md diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 06dcb19..f1de3f6 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -52,7 +52,15 @@ Can you include a page from someone else’s book into your own using `external: 7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +8. When viewing your book online, 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} ..\figures\external_page_attribution.png +:name: external_page_attribution +:width: 100% +:alt: Attribution box shown at the top of an external page + +Attribution box that appears at the top of an external page. +``` ```{admonition} Check your understanding :class: note diff --git a/book/figures/external_page_attribution.png b/book/figures/external_page_attribution.png new file mode 100644 index 0000000000000000000000000000000000000000..86d82863ecaf2a3e4727e21b60f02fb7ffca8c39 GIT binary patch literal 6996 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 F`CpHvV-x@Y literal 0 HcmV?d00001 From 6701caf92b1195ece0f2e7b2e99ea7eb109e4a79 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 17 Jun 2025 20:03:27 +0200 Subject: [PATCH 15/18] update figure --- book/exercises/005a.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index f1de3f6..4822470 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -54,12 +54,12 @@ Can you include a page from someone else’s book into your own using `external: 8. When viewing your book online, 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} ..\figures\external_page_attribution.png +```{figure} ../figures/external_page_attribution.png :name: external_page_attribution :width: 100% -:alt: Attribution box shown at the top of an external page +:alt: Example of attribution box shown at the top of an external page -Attribution box that appears at the top of an external page. +Example of attribution box at the top of an external page. ``` ```{admonition} Check your understanding From 237b43b56e17aab4a6192fca3f95fa3a2fee1c5a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 18 Jun 2025 13:20:02 +0200 Subject: [PATCH 16/18] link to external figure --- book/exercises/005a.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index 4822470..b213bbc 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -54,7 +54,7 @@ Can you include a page from someone else’s book into your own using `external: 8. When viewing your book online, 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} ../figures/external_page_attribution.png +```{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 From ac4e319dd5fb62b272d2983bf6b4b7be6baf1b94 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 18 Jun 2025 13:20:29 +0200 Subject: [PATCH 17/18] Delete book/figures/external_page_attribution.png --- book/figures/external_page_attribution.png | Bin 6996 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 book/figures/external_page_attribution.png diff --git a/book/figures/external_page_attribution.png b/book/figures/external_page_attribution.png deleted file mode 100644 index 86d82863ecaf2a3e4727e21b60f02fb7ffca8c39..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6996 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 F`CpHvV-x@Y From 45253e3c7e6448fb8bd3c1e130d45ee66016eb24 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 18 Jun 2025 13:23:29 +0200 Subject: [PATCH 18/18] Update 005a.md --- book/exercises/005a.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/book/exercises/005a.md b/book/exercises/005a.md index b213bbc..e46cf3b 100644 --- a/book/exercises/005a.md +++ b/book/exercises/005a.md @@ -25,34 +25,34 @@ Can you include a page from someone else’s book into your own using `external: - external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md ``` -2. Add the `external:` link into the `parts:` or `chapters:` section of your `_toc.yml` file. +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: +`_toc.yml` snippet: - ```yaml - format: jb-book - root: intro +```yaml +format: jb-book +root: intro - chapters: +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 `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 `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. - -8. When viewing your book online, 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. +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