diff --git a/README.md b/README.md index 1cc2048..e481409 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,33 @@ # Template -This is the template book. You can fork this to create a book in as easy-as-possible a way. Focus is mostly on providing a clean and simple view to the key setup of our book repo. +This is the template book. You can use this book as a template to start your own TeachBook in as easy-as-possible a way. -## To be update, use this repository as a template, not as a fork +# Steps to use this template and publish it online -## How to deploy a fork of this book on GitHub Pages +1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template: -1. Click `Fork`, and set a name for your new book. -2. To enable deploying via GitHub Actions, go to `⚙ Settings`, then to `Pages`, and under `Build and Deployment` set `Source` to `GitHub Actions`. -3. To trigger a deployment for the first time, you can go to `Actions` (top panel), then click `deploy-book` on the left, then `Run workflow` on the right. The book is also automatically deployed whenever commits are pushed (in absence of errors). +![use template](https://teachbooks.tudelft.nl/jupyter-book-manual/_images/use_template.png) -Voila! You can now access the copy of the template at -`https://.github.io//` (e.g. https://teachbooks.github.io/template). +2. Fill in a repository name, this name will be used in the future url of your book: -It is possible to have multiple versions of a book published at once, by creating another Git branch (e.g. `draft` or `dev`). -For each branch, the respective book is published at `https://.github.io//`. -Technical note: for convenience, just `https://.github.io//` redirects to `https://.github.io//book/`, which is itself an alias (a symlink) to -`https://.github.io//main/`. +![create new repository](https://teachbooks.tudelft.nl/jupyter-book-manual/_images/create_new_repository.png) -To learn more about how we do this, please see the [GitHub Actions documentation](https://docs.github.com/en/actions) and our deployment pipeline configuration file `.github/workflows/deploy-book-ghpages.yml`. +3. Set source for GitHub pages to under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: + +![activate pages](https://teachbooks.tudelft.nl/jupyter-book-manual/_images/set_up_pages.png) + +4. Set repository website as your GitHub Pages website under `Code`- `About` - - `Website` - `Use your GitHub Pages Website` + +![GitHub pages as website](https://teachbooks.tudelft.nl/jupyter-book-manual/_images/use_github_pages_website.png) + +4. Wait a few minutes for the website to be deployed, if you're curious, have a look at the progress under `Actions` - `All workflows`: + +![action](https://teachbooks.tudelft.nl/jupyter-book-manual/_images/action.png) + +5. When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. + +To learn more about how we do this, please see the [GitHub Actions documentation](https://docs.github.com/en/actions) and our deployment pipeline configuration file `.github/workflows/deploy-book-ghpages.yml` [here](https://github.com/TeachBooks/template/blob/main/.github/workflows/deploy-book-ghpages.yml). \ No newline at end of file