Write book fully in GitHub interface

Write book fully in GitHub interface#

Using the GitHub tooling in combination with TeachBook’s software, users are able to write their book fully online, without the need to install any software locally. This is especially useful for users that are not familiar with Git and GitHub, or do not have the rights to install software on their computer. To make this possible, users can start with the TeachBooks Template after which they make use of the Deploy Book Workflow to automatically build and release their book online.

How to do this#

New users can start writing their book by following the steps shown in the TeachBooks Template repository.

Users who already have a TeachBook repository can add the Deploy Book Workflow as explained here.

After that, users can start writing and editing their book fully online in the GitHub interface. This is supported with:

  • Automatic book builds for all version. See Share book online for multiple versions for more information

  • A summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured

Example of summary#

Whenever the workflow is triggered, its progress and a summary can be seen under the Actions- All workflows - call-deploy-book in GitHub! It shows you a descriptive summary. This summary includes, among others, the errors in the build process per branch and where the book is released online.

Here’s an example for a summary for the template book:

Branches deployed

Branch 🎋

Link 🔗

Build status ☑️

main

https://teachbooks.github.io/template/main

✅ Released

version2

https://teachbooks.github.io/template/version2

🔴 Build failed [1]

version3

https://teachbooks.github.io/template/version3

⭕ Build failed [2]

Legend for build status

✅ Released - build success, new version released.

🔴 Build failed [1] - build failure, previous version of the book reused.

⭕ Build failed [2] - build failure, no previous version reused.

Preview of build errors & warnings

For more details please see the corresponding build-books jobs in the left pane.

On branch version2:

�[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]�[39;49;00m

On branch version3:

/home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found

Exercise#

Check out the exercises in the TeachBooks template to see for yourself how you can write and edit your book fully online in GitHub!

Contents