admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-13 14:55:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'release' into 30-add-section-on-icons

Browse source
This commit is contained in:
xjulie0x 2024-12-29 18:57:54 +01:00 • committed by GitHub
commit 80a0e443a6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
82 changed files with 3829 additions and 489 deletions
Download patch file Download diff file Expand all files Collapse all files

8
book/basic-features/external-features.md
View file

@ -1,8 +0,0 @@
# Externally Developed Features
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
This chapter includes features useful for books in the educational context, developed by various parties.

5
book/basic-features/hypothesis.md
View file

@ -1,5 +1,10 @@
# Making comments on the website: Hypothesis
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.

19
book/basic-features/utterances.md
View file

@ -1,13 +1,22 @@
# Discussions in your book: Utterances
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
{bdg-white}`GitHub app and Javascript script`
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
The [utterances website](https://utteranc.es/) clearly explains the required steps. One thing to take care of is how you want to do the issue-mapping with respect to multiple deployed versions (draft version, student version, archived versions):
- `Issue title contains page pathname`/`Issue title contains page URL` is useful if you want to isolate the comments on each of the branches.
- `Issue title contains page title` is useful if you want to show the all comments on all different branches.
The [utterances website](https://utteranc.es/) clearly explains the required steps. Three things to take care of are:
1. With the current setup of the [deploy book workflow on GitHub](../external/deploy-book-workflow/README.md), this widget only works on the primary branch.
2. The baseurl is the root url of your book (the part of the url that doesn't change when opening different pages of the book). It needs to be defined in the `_config.yml` so that utteranc.es knows where to redirect users while interacting with the widget:
```
html:
baseurl : "https://<user/organization>.github.io/<repo>" #Replace this with your own URL
```
3. It's advised to use `Issue title contains page pathname` as an option on utteranc.es, because that url is most stable.
The given script can be added anywhere in your book, just copy the html-script into your `.md`-file or a markdown cell in your `.ipynb`-file. The blogpost is not visible when you do a local build of the book, build it online or use a local python server as shown in {ref}`setup-local-server`.
@ -24,4 +33,4 @@ Below you see an example of this feature!
theme="github-light"
crossorigin="anonymous"
async>
</script>
</script>