How to make this website¶
All the files needed to build this website can be found in our github repository.
This website is built using several technologies you will need to install and learn to use:
The contents of the book are made up of jupyter notebooks which are made in Jupyter Lab. Extra documentation for writing markdown (the text cells) can be found here.
We also use javascript to make animations, specifically using the p5.js library. We recommend writing the code for the animations in the online p5.js editor in instance mode before adding them to the website.
To create html files out of the jupyter notebooks, and configure a table of contents among other nice features, we use jupyter-book (We prefer using the linux version). Note that you should delete the _build folder entirely before rebuilding it to ensure that the javascript is added correctly.
This box was made using MyST syntax
When making html files from jupyter notebooks, you can use MyST syntax, which is fancy markdown, to create expandable cells and more. Note that MyST syntax will look broken and ugly in the jupyter notebook, but not in the generated html files!
To turn the html and javascript files into an actual website on the internet we use github pages. Simply add the generated html files from the _build folder into a docs folder (and add a file named .nojekyll) on a github repository with github pages enabled, and the website will be online.
The commands that need to be run to do these things when using a linux terminal can be found in this script in our repository. You should just run this script using the command ./build_docs.sh when building the website, to make things faster and to not accidentally delete anything.
Combining notebooks and javascript¶
This is my own solution on how best to do this, so there are definetely better ones out there. The special problem with combining notebooks and javascript is that every page in the entire generated website uses the same javascript code! So you need to use unique ids and a helper function to run the correct animations in the correct places, and only those places.
Where you want your p5.js canvas to appear in your notebook, you create a markdown cell with this html snippet:
<article id="canvas_id"></article>
where you change "canvas_id" into whatever unique id you think fits. Note that the canvas and animation will not appear in the notebook, only in the generated html files.
The p5.js code written in instance mode should be added to the _static folder that jupyter-book uses. This code should not create canvases on its own, which means it should not have a setup function not in instance mode, nor new p5() anywhere. An example of such files can be found in our github repository. Remember to include the p5.js library in the _static folder. The canvases are created from the single setup() function in the initialize.js file, which you should also put in the _static folder. This file should look as follows:
function setup() {
// id: function pairs
var functions = {
orbitsketch: orbit,
starsketch: starfield,
vectorsketch: vectors,
};
var myEle;
for (var id in functions) {
myEle = document.getElementById(id);
if(myEle) {
let sketch = new p5(functions[id], id);
}
}
}
when you want to add an animation, you write the p5.js instance mode javascript code with some function wrapping the whole thing, you add the html with the unique id to a notebook, and you add the id-function name pair to the dictionary in the initialize.js file you see above. As an example, “orbitsketch” is an id, and “orbit” is a function name in the code above.