It only takes 10 clicks!

It only takes 10 clicks!#

../_images/template.jpg

Now that you’ve been introduced to the basics of a Jupyter Book, let’s make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.

1. Create a GitHub account#

TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).

Exercise 1

If you don’t already have one, create a GitHub account here by visiting github.com/signup.

2. Use the template—it’s really just 10 clicks!#

Now, let’s make a book: we’ve made a template on GitHub which carries out most of the technical steps required to create a book and put it online. Instructions for using the template are in the README of the TeachBooks Template repository on GitHub, which is by default visible on the repository homepage.

Exercise 2

Go to the TeachBooks Template repository on GitHub and follow the instructions to create your book. At the end, it should be visible at <your_username>.github.io/<book>. When finished, come back to this page.

3. Let’s practice!#

Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.

The exercises can be found in your book at https://<username or organiszation_name>.github.io/<repository_name>/exercises/exercises (case sensitive) or at https://teachbooks.io/template/exercises.html.

../_images/exercises.png

Tip

Maybe you’re already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents. In that case, can you answer the following questions (refering to the exercises):

  1. Can you add some content to the intro page?

  2. Can you add the file named file_to_be_added_to_toc.md to the book website?

  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?

If something is not clear, dive into to the relevant exercise page.

Contents