You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+34-19Lines changed: 34 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,35 +1,50 @@
1
-
# GitHub workflow to publish online to GitHub Pages
1
+
# GitHub workflow: publish your book online to GitHub Pages
2
2
3
+
<<<<<<< Updated upstream
3
4
We developed a workflow which builds the TeachBooks in your repository for all branches, and publishes them online via GitHub Pages.
5
+
=======
6
+
```{admonition} User types
7
+
:class: tip
8
+
This page is useful for user type 3, 4 and 5.
9
+
```
4
10
5
-
It has the following features:
11
+
We developed a workflow which builds your TeachBook in your repository for all branches and publishes them online via GitHub Pages. In simplified terms, it builds the website based on your repository.
12
+
>>>>>>> Stashed changes
13
+
14
+
The [TeachBooks Template](https://github.com/TeachBooks/template) uses this functionality for example. The workflow `call-deploy-book.yml` calls the `deploy-book.yml` workflow, which builds the Jupyter books at the calling repository for all branches, and deploys them via GitHub Pages.
15
+
16
+
The workflow has the following features:
6
17
- Publishing of your [TeachBook](https://teachbooks.tudelft.nl/)-repository (built with [Jupyter Book](https://github.com/executablebooks/jupyter-book)) to GitHub Pages
7
-
- Publishes both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories. GitHub Teams is free for teacher as described in the [GitHub documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers). If you’ve a organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the [GitHub website](https://github.com/team#organizations).
8
-
- Publishing all or a selection of branches, allowing to build draft version of the TeachBook online preventing local builds
9
-
- A summary describing where the TeachBook is published, errors in the build process per branch and how the publish step is configured
10
-
- Caching of build books so that it can be reused when another branch is published or the next build contains critical errors
18
+
- Ability to publish both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories.
19
+
GitHub Teams is free for teachers as described in the [GitHub documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers).
20
+
If you have an organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the [GitHub website](https://github.com/team#organizations).
21
+
- Publishing all or a selection of branches, allowing to build a draft version of the TeachBook online which reduces the need for local builds of the book
22
+
- Provides a summary describing where the TeachBook is published, errors in the build process per branch and how the publish step is configured
23
+
- Caching of already built books so that it can be partially reused when another branch is published or the next build contains critical errors
11
24
- Caching of python environment to speed up the workflow
12
25
- Allowing to use submodules within your book
13
26
- Customizable trigger for the workflow itself
14
27
- Optionally preprocess branches using the [`teachbooks` package](https://github.com/TeachBooks/TeachBooks).
15
28
- Converting branch-names to well-defined URLs
16
-
- Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these setting are ill-defined or conflicting. Although aliases are not allowed by GitHub Pages, it seems you can use one alias, but not more.
17
-
- Redirects the root directory to one of the branches or copy one of the branches to root.
29
+
- Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these settings are ill-defined or conflicting. Although aliases are not allowed by GitHub Pages, it seems you can use one alias, but not more.
30
+
- Redirects the root directory to one of the branches or copies one of the branches to root.
18
31
- Adds an 'archived'-banner to old branches / branches of previous years.
19
32
20
-
The [TeachBooks template book](https://github.com/TeachBooks/template) uses this functionality for example: The workflow `call-deploy-book.yml` calls the `deploy-book.yml` workflow, which builds the Jupyter books at the calling repository for all branches, and deploys them via GitHub Pages.
21
-
22
33
## How to start using this workflow
23
-
This workflow is used in `TeachBooks/template`. Feel free to use it for your TeachBook as well:
34
+
As previously mentioned, this workflow is used in `TeachBooks/template`. Feel free to use it for your TeachBook as well:
24
35
1. Add [`teachbooks`](https://github.com/TeachBooks/TeachBooks) to your `requirements.txt` file in your root folder
25
36
2. Move all the TeachBook files (including `_config.yml` and `_toc.yml`) to a subdirectory `book/`.
26
-
3. Copy the [`call-deploy-book.yml` workflow](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/call-deploy-book.yml) to the `/.github/workflows` folder in your repository.
37
+
3. Copy the [`call-deploy-book.yml`](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/call-deploy-book.yml) workflow to the `/.github/workflows` folder in your repository.
## Customize the workflow: TeachBook publishing settings
47
+
>>>>>>> Stashed changes
33
48
34
49
You can adapt the behaviour by setting repository variables as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). Define the following repository variables:
35
50
-`PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables.
@@ -38,26 +53,26 @@ You can adapt the behaviour by setting repository variables as explained [here](
38
53
-`BEHAVIOR_PRIMARY` which is set to `redirect` whenever it's not defined in the repository variables.
39
54
- This indicates whether to copy the PRIMARY_BRANCH to root ('copy') or redirect from root to the PRIMARY_BRANCH ('redirect')
40
55
- Advised to use 'redirect' if you expect to archive a version in the future so that the URL doesn't change for the reader.
41
-
-`BRANCH_ALIASES` which is set to ``(space) whenever it's not defined in the repository variables.
56
+
-`BRANCH_ALIASES` which is set to `` (just a space) whenever it's not defined in the repository variables.
42
57
- This defines an alias (custom URL) for a branch
43
-
-Variable should be an Space-separated list of branch names, e.g. 'alias:really-long-branch-name`
44
-
- If no alias is wanted, `BRANCH_ALIASES` may be set to ' ' (space).
58
+
-Variables should be a space-separated list of branch names, e.g. 'alias:really-long-branch-name`
59
+
- If no alias is wanted, `BRANCH_ALIASES` may be set to `` (just a space)
45
60
-`BRANCHES_TO_DEPLOY` which is set to `*` (all branches) whenever it's not defined in the repository variables.
46
61
- This defines the branches to deploy.
47
62
- It should be a space-separated list of branch names, e.g. 'main second third'.
48
-
-`BRANCHES_TO_PREPROCESS` which is to to `` (space, no branch) whenever it's not defined in the repository variables
63
+
-`BRANCHES_TO_PREPROCESS` which is to to `` (just a space = no branch) whenever it's not defined in the repository variables
49
64
- This defines the branches to preprocess with the [`TeachBooks` package](https://teachbooks.github.io/TeachBooks/cli/cli.html#cmdoption-teachbooks-build-publish), which removed book-pages and config lines defined with `# START REMOVE FROM PUBLISH` and `# END REMOVE FROM PUBLISH`
50
65
- It should be a space-separated list of branch names, e.g. 'main second third'.
51
66
- If no preprocessing is required, `BRANCH_TO_PREPROCESS` may be set to ' ' (space).
52
67
-`BRANCHES_ARCHIVED` which is set to `` (space, no branch) whenever it's not defined in the repository variables
53
68
- This adds a banner to the published branch: You are viewing an archived version of the book. Click here for the latest version.
54
69
- It should be a space-separate list of branch names, e.g. 'main second third'.
55
70
56
-
In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch trigger the workflow. You can limit the branches or subdirectories.
71
+
In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch triggers the workflow. You can limit the branches or subdirectories.
57
72
58
-
## Workflow progress and summary
73
+
## View the workflow progress and summary
59
74
60
-
Whenever the workflow is triggered, progress and a summary can be seen under the <svgaria-hidden="true"height="16"viewBox="0 0 16 16"version="1.1"width="16"data-view-component="true"class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <pathd="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub. It shows you a descriptive summary:
75
+
Whenever the workflow is triggered, its progress and a summary can be seen under the <svgaria-hidden="true"height="16"viewBox="0 0 16 16"version="1.1"width="16"data-view-component="true"class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <pathd="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub! It shows you a descriptive summary:
61
76
- Ill-defined repository configuration variables (in `Annotations`)
62
77
- Which branches are published and where (`https://<username/organization_name>.github.io/<repository_name>` (case sensitive)) including which branch is published on the website root and the applied alias
0 commit comments