Exercise 4: Your Version of the Book

Exercise 4: Your Version of the Book#

By now, we’ve covered the essentials: content files, _toc.yml and _config.yml. But what if you want to make some changes but don’t want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let’s try and do that! Later on, you’ll probably want to merge your newest version back into the original book. That’s what we’ll do in Exercise 5: Merge your version in the original book.

Can you make a new branch of your book with an additional file file_on_new_version.md and view it online?

  1. Add a new Issue to let people know you’re working on something by going to your repository - Issues - New issue (note that is not required for making your own version, but it’s good practice so that people know where you’re working on)

  2. Add a title and description, eg. Added some content

  3. On Assignees, click Assign yourself to make clear that you feel responsible for this issue.

  4. Click Submit new issue

  5. In the new window, under Development, click Create a branch (note that you could also make branches in other ways, but in this way it’s directly linked to the issue). A ‘branch’ is a separate version of the book which keeps the link with the original book.

  6. Use the default options and click Create branch

  7. Ignore the checkout in your local repository- popup for now (later on you’ll know what this is and how to use it)

  8. Go to Code - main and click on 1-<your_issue_title> to open your branch.

  9. Add a book page as explained in Exercise 2: Add a new file to the table of contents and make sure you commit to the 1-<your_issue_title>-branch.

  10. Go to Actions - The most recent workflow run Update _toc.yml / the commit message of the commit you just made - Wait for it to finish - In the summary, you should now see multiple Branches. Click on the link of your new branch ``1-<your_issue_title>`

  11. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to refresh the page.

Check your understanding

Before moving on to the next exercise, make sure you understand the following:

  • What is the purpose of creating a new branch in your repository?

  • Why is it good practice to create an issue before starting work on a new feature or change?

  • How can you view the changes made in your new branch online?