Forgejo as a Notetaking Tool
This article has a corresponding repo on my Gitlab
Introduction
Forgejo (formerly Gitea) can serve as a nice alternative to Gollum. I played with Gollum in the past but I found it slow and a litte cumbersome, wheras Forgejo is fast and lightweight.
Math
The markdown files in Forgejo support math via KaTeX 1, however, other formats are not yet supported (see e.g. 2). KaTeX can be added in a template 3 that calls the auto-render extension.
To host it locally KaTeX can be run locally. Usually this would involve making the source accessible on the server, a feature that is supposedly implemented 4 by serving files under /data/gitea/public/assets at localhost:3000/assets. Unfortunately, this doesn’t seem to work in the current release [2023-10-14], try as I might, files do not show up (I suspect this may be related to docker).
To work-around this create a docker image with katex in it:
FROM alpine
# Download a local copy of katex
RUN apk update; apk add python3 wget nodejs npm
RUN wget 'https://github.com/KaTeX/KaTeX/releases/download/v0.16.9/katex.tar.gz'
RUN tar -xzf katex.tar.gz
RUN mv katex dist
RUN cd dist; npm install http-server
CMD cd dist; node_modules/http-server/bin/http-server -p 8080 --corsadd it to the compose file:
services:
katex:
image: katex
container_name: katex
ports:
- 57359:8080
server:
# image: codeberg.org/forgejo/forgejo:1.20
image: forgejo-extra-dep
# image: forgejo-patched-bleve
container_name: forgejo
environment:
- USER_UID=1000
- USER_GID=1000
restart: always
volumes:
- ./forgejo_data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
ports:
- '3000:3000'
- '222:22'Then finally, modify the template from [^3] to automatically detect the domain name:
<script>
function addScript(src, callback){
var s = document.createElement('script');
s.setAttribute('src', src);
s.onload=callback;
document.body.appendChild(s);
}
function addStylesheet(href){
var l = document.createElement('link');
l.setAttribute('href', href);
l.setAttribute('rel', 'stylesheet');
l.setAttribute('crossorigin', 'anonymous');
document.head.appendChild(l);
}
const hostname = window.location.hostname;
addStylesheet(`http://${hostname}:57359/katex.css`);
addScript(`http://${hostname}:57359/katex.min.js`, function(){
addScript(`http://${hostname}:57359/contrib/auto-render.min.js`, function() {
renderMathInElement(document.body, {
delimiters: [
{left: '$$', right: '$$', display: true},
{left: '$', right: '$', display: false},
{left: '\\(', right: '\\)', display: false},
{left: '\\[', right: '\\]', display: true}
],
throwOnError : false
});
});
});
</script>Note that:
- the webserver for katex must implement
--cors - Javascript doesn’t have parser blocking, so it’s important to load the scripts in order
Rendering Jupyter Notebooks
To render jupyter, add the following to app.ini:
[markup.jupyter]
ENABLED = true
FILE_EXTENSIONS = .ipynb
RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
[markup.sanitizer.jupyter.img]
ALLOW_DATA_URI_IMAGES = trueand make sure that the docker image has the necessary packages:
FROM codeberg.org/forgejo/forgejo:1.20
# Dependencies for previewing all file types
RUN apk --no-cache add asciidoctor freetype freetype-dev gcc g++ libpng libffi-dev py-pip python3-dev py3-pip py3-pyzmq pandoc
# Dependencies needed for compiling from source
# This is not needed but I've left it for debugging purposes
RUN apk update; apk add make nodejs npm gcc musl-devI also found it helpful to add .docx and .tex, this was useful when adapting past teaching material.