From 3e530793f7703eb1f55efe68964e290eb2728499 Mon Sep 17 00:00:00 2001
From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl>
Date: Tue, 16 Apr 2024 21:31:06 +0200
Subject: [PATCH] Added utterances to manual

---
 book/_toc.yml                     |  1 +
 book/basic-features/hypothesis.md |  7 +++++--
 book/basic-features/utterances.md | 18 ++++++++++++++++++
 3 files changed, 24 insertions(+), 2 deletions(-)
 create mode 100644 book/basic-features/utterances.md

diff --git a/book/_toc.yml b/book/_toc.yml
index d9775ac..6c77dc0 100644
--- a/book/_toc.yml
+++ b/book/_toc.yml
@@ -28,6 +28,7 @@ parts:
       sections:
       - file: basic-features/recipes.md
       - file: basic-features/hypothesis
+      - file: basic-features/utterances
     - file: features/overview
       sections:
       - file: features/github_deploy.md
diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md
index 20b6043..11a0ce1 100644
--- a/book/basic-features/hypothesis.md
+++ b/book/basic-features/hypothesis.md
@@ -1,6 +1,6 @@
-# Making comments on the website with Hypothesis
+# Making comments on the website: Hypothesis
 
-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; an alternative is Utterances, but this is only available for GitHub-hosted books.
+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.
 
 ```{admonition} Be careful of changing website URL's!
 :class: warning
@@ -35,8 +35,11 @@ You can find out more about the draft and publish feature on {ref}`this page <pu
 
 Once on the draft version of this page, look at the top right corner: you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension and allow you to view the annotations. Create an account and log in if you would like to reply or make your own annotations. You can also highlight text, but this is not publicly visible, it is only for your own reference.
 
+## Student-controller with browser extension
 Note that the annotations are only visible for the page that you are currently viewing. You can see all the Annotations on a website by opening the "Public" menu at the top of the dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`).
 
+As an alternative to activating this for everyone, you can also advise your students to use the [hypothesis browser extension](https://web.hypothes.is/start/). In this way, students are not distracted by potential unnecessary public annotation and comments by fellow students and teachers.
+
 % THIS IS ADDED TO PAGE AS ANNOTATION:
 % This is an example Annotation. Note that annotations are publicly visible, but you must create an account and be logged in to reply or make your own. You can make highlights, but they are only visible to you, not everyone. You can also see all the Annotations on a website by opening the "Public" menu at the top of this dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`).
 
diff --git a/book/basic-features/utterances.md b/book/basic-features/utterances.md
new file mode 100644
index 0000000..097c3a3
--- /dev/null
+++ b/book/basic-features/utterances.md
@@ -0,0 +1,18 @@
+# Discussions in your book: Utterances
+
+[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. 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`.
+
+Users need to have a GitHub-account to post a message. Although this might be a burden, it allows students to track their previous posts and set up notifications on follow-up posts.
+
+Below you see an example of this feature!
+
+## Example discussion
+<script src="https://utteranc.es/client.js"
+        repo="TeachBooks/utterances_manual"
+        issue-term="pathname"
+        theme="github-light"
+        crossorigin="anonymous"
+        async>
+</script>
\ No newline at end of file