mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-13 06:45:52 +00:00
46 lines
3.1 KiB
Markdown
46 lines
3.1 KiB
Markdown
# It only takes 10 clicks!
|
|
|
|
```{figure} figures/template.jpg
|
|
---
|
|
name: template
|
|
width: 150px
|
|
align: right
|
|
```
|
|
|
|
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}
|
|
|
|
If you don't already have one, create a GitHub account here by visiting [github.com/signup](https://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}
|
|
|
|
Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBooks/template) 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 as part of an introductory **workshop**. 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.
|
|
|
|
```{exercise}
|
|
Work through the exercises attached to this page (you can find them in the left sidebar). These exercises can also be found in the template book itself.
|
|
```
|
|
|
|
```{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.
|
|
```
|
|
|