user types in margins

book/features/HTML_javascript.md

@@ -1,4 +1,4 @@
-# Interactive HTML/JavaScript elements
+````{margin}
 
 ```{admonition} User types
 :class: tip
@@ -6,6 +6,9 @@ This section is useful for user type 5.
 ```
 
 {bdg-danger}`iframe`
+````
+
+# Interactive HTML/JavaScript elements
 
 In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
 

book/features/adding_HTML_elements.md

@@ -1,6 +1,8 @@
-# Adding interactive HTML/JavaScript elements
-
+````{margin}
 {bdg-danger}`iframe`
+```` 
+
+# Adding interactive HTML/JavaScript elements
 
 In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
 

book/features/apa.md

@@ -1,12 +1,14 @@
-(apa)=
-# APA References
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4 and 5.
 ```
 
 {bdg-primary}`(To be converted into) Sphinx Extension`
+````
+
+(apa)=
+# APA References
 
 ```{note}
 This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more.

book/features/custom-launch-button.md

@@ -1,11 +1,13 @@
-# Multilingual book
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4 and 5.
 ```
 {bdg-primary}`Sphinx Extension`
 
+````
+
+# Multilingual book
 The custom launch button extension allows you to create a customizable button in the top right of your jupyter book. 
 This may have many applications, one of them being that you can create different language versions of the book available for the user. 
 

book/features/easy-editing.md

@@ -1,8 +1,10 @@
-# Easy Editing Process
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
+````
+
+# Easy Editing Process
 
 The following tools are created by TeachBooks to ease the process of making books. We acknowledge that making books is a difficult process; it requires advanced knowledge on CLI, python packages, html-files, data-storage and website hosting. The tools in this chapter are intended for those users who lack knowledge on these topics (which includes most of the TeachBooks' community members itself).

book/features/external_toc.md

@@ -1,12 +1,14 @@
-(external-toc)=
-# Sharing content between books in table of contents
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This page is useful for user type 3-5.
 ```
 
 {bdg-secondary}`Python Package: teachbooks`
+````
+
+(external-toc)=
+# Sharing content between books in table of contents
 
 ## Introduction
 

book/features/h5p.md

@@ -1,11 +1,13 @@
-# H5p interactive elements
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
 
 {bdg-danger}`iframe`
+````
+
+# H5p interactive elements
 
 ## Instruction
 H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. An H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):

book/features/jupyterquiz.ipynb

@@ -7,14 +7,16 @@
     "hidePrompt": true
    },
    "source": [
-    "# JupyterQuiz\n",
-    "\n",
+    "````{margin}\n",
     "```{admonition} User types\n",
     ":class: tip\n",
     "This section is useful for user type 4-5.\n",
     "```\n",
     "\n",
-    "- {bdg-secondary}`Python Package: jupyterquiz`\n",
+    "{bdg-secondary}`Python Package: jupyterquiz`\n",
+    "````\n",
+    "\n",
+    "# JupyterQuiz\n",
     "\n",
     "JupyterQuiz is a code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file. An example is given below:\n",
     "\n",

book/features/live_code.ipynb

@@ -4,12 +4,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Interactive content: Run Python inside your book\n",
-    "\n",
+    "````{margin}\n",
     "```{admonition} User types\n",
     ":class: tip\n",
     "This section is useful for user type 5.\n",
     "```\n",
+    "```` \n",
+    "\n",
+    "# Interactive content: Run Python inside your book\n",
     "\n",
     "{bdg-primary}`Sphinx Extension`\n",
     "\n",

book/features/local_server.md

@@ -1,12 +1,14 @@
-(setup-local-server)=
-# Local Server to view interactive elements locally
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This section is useful for user type 4-5.
 ```
 
 {bdg-secondary}`Python Package: teachbooks`
+````
+
+(setup-local-server)=
+# Local Server to view interactive elements locally
 
 Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books.
 

book/features/plotly.ipynb

@@ -7,12 +7,14 @@
     "hidePrompt": true
    },
    "source": [
-    "# Interactive plots: plotly\n",
-    "\n",
+    "````{margin}\n",
     "```{admonition} User types\n",
     ":class: tip\n",
     "This section is useful for user type 5.\n",
     "```\n",
+    "````\n",
+    "\n",
+    "# Interactive plots: plotly\n",
     "\n",
     "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript."
    ]

book/features/pull_request_build.md

@@ -1,9 +1,11 @@
-# Build pull requests from forks
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This section is useful for user type 3-5.
 ```
+````
+
+# Build pull requests from forks
 
 When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, **Read the Docs** is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page!
 

book/features/sphinx_extensions.md

@@ -1,8 +1,10 @@
-# Additional functionality
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This section is useful for user type 4-5.
 ```
+````
+
+# Additional functionality
 
 This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file.

book/features/students.md

@@ -1,8 +1,11 @@
-# TeachBooks Student-view Features
-
+````
 ```{admonition} User types
 :class: tip
 This section is useful for user type 1-5.
 ```
+````
+
+# TeachBooks Student-view Features
+
 
 This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach. These tools could also be useful for other users.

book/features/teachbooks.md

@@ -1,5 +1,4 @@
-(teachbooks-package)=
-# Draft-Release Workflow
+````{margin}
 
 ```{admonition} User types
 :class: tip
@@ -8,6 +7,11 @@ This page is useful for user type 3-5.
 
 {bdg-secondary}`Python Package: teachbooks`
 
+````
+
+(teachbooks-package)=
+# Draft-Release Workflow
+
 Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow <deploy-book-workflow>`, which builds our TeachBooks).
 
 ```{admonition} Why is this useful?

book/features/update_env.md

@@ -1,11 +1,13 @@
-# Auto-updating packages
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This page is useful for user type 4-5.
 ```
 
 {bdg-dark}`Git Workflow`
+````
+
+# Auto-updating packages
 
 When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options:
 1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when new version come out, although new version are in general backwards compatible.

book/features/versioning.md

@@ -1,6 +1,10 @@
-# TeachBooks Versioning
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>````
+````
 
-> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
+# TeachBooks Versioning
 
 Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors:
 

book/features/visuals.md

@@ -1,8 +1,10 @@
-# Book styling
-
+````{margin}
 ```{admonition} User types
 :class: tip
 This section is useful for user type 1-5.
 ```
+````
+
+# Book styling
 
 TeachBooks developed a few improvements of the book which improve the visual book styling.