Amiga Project

Bouwen Documentatie Site

5 min read

Onderzoek

Na onderzoek vond ik snel veel manieren om mijn Obsidian Vault gratis om te zetten in een website. Dit is natuurlijk ideaal, aangezien ik bij aanvang van mijn stage begonnen ben met het vastleggen van de genomen stappen in Obsidian.

Ik heb besloten om Quartz te gebruiken, omdat:

  • Quartz veel gebruikt wordt, en er dus veel materiaal over te vinden is.
  • Quartz origineel gebouwd is voor Obsidian en dus geweldige support heeft voor dit platform.
  • Quartz snel op te zetten is.
  • Quartz het naar een statische site bouwt die ik makkelijk op mijn VPS kan zetten.

Ik heb besloten om het op https://amiga.pkg-dot-zip.com/ te zetten omdat ik al over dit domein bezit en er dus geen extra kosten aan verbonden zijn.

Het installeren van Quartz

Op de site staat:

Quartz requires at least Node v22 and npm v10.9.2

Priem! Dit installeren we door het volgende in de terminal uit te voeren:

sudo apt install nodejs
sudo apt install npm

Om te checken of dit gelukt is kan je -v uitvoeren om de versie te checken:

node -v
npm -v

Als dit NIET versie 22 of nieuwer is van nodejs kan je de stappen ondernemen die hier staan. Dit was bij mij ook het geval.

Working Directory

Nu gaan we working directory opzetten. Navigeer naar een mapje dat je goed kan onthouden. In mijn geval:

cd ~
cd Documents
mkdir QuartzWorkingDir
cd QuartzWorkingDir

De daadwerkelijke installatie

Nu moet je dit regel voor regel uitvoeren:

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz create

Hierbij kom je door een setup menuutje. Super schattig natuurlijk! Ik creer zometeen een shell scriptje die je vault kopieert naar de content folder, omdat ik geen symlink wil gebruiken i.v.m. veiligheid. Selecteer bij de eerste stap dus dat je een lege content folder wilt maken.

In stap 2 vraagt Quartz hoe je linkjes wilt afhandelen. Dit kan je altijd nog later aanpassen, maar ik houd het bij de standaard optie.

Het gebruik van Quartz

Generiek gebruik

Voor hoe je Quartz verder kan gebruiken refereer ik naar de volgende paginas:

Ik raad ook aan om al je bestanden te voorzien van de juiste metadata (frontmatter).

Welke stappen heb ik ondernomen?

Nginx

Ik heb de site op mijn VPS staan. Instructies over zelfhosting met nginx vind je hier.

Maken hoofdpagina

Op de Authoring Content pagina staat dat het index.md bestand de hoofdpagina is. Daarom heb ik een placeholder pagina gemaakt in mijn Obsidian Vault hiervoor met de naam index.

Warning

‘index.html’ is met een KLEINE LETTER. Daarom moet je dus ook je markdown bestand in je Obsidian Vault beginnen met een kleine letter. Doe je dit niet, dan zul je statuscode 403 terugkrijgen.

Automatisering

Wij willen in principe dat de content folder het enige is wat wij continue aanpassen. Custom CSS bestanden (bijvoorbeeld voor custom callouts) en de configuratie willen we gewoon in de quartz folder doen.

Ik heb hier een shell scriptje gemaakt die je vault kopieert naar de content folder en gelijk quartz bouwt.

#!/bin/bash
 
QUARTZ_DIR=~/Documents/QuartzWorkingDir/quartz  # Change this to your Quartz folder path
OBSIDIAN_VAULT=~/path/to/your/obsidian/vault      # Change this to your Obsidian vault path
 
# Navigate to Quartz dir
cd "$QUARTZ_DIR" || { echo "Quartz directory not found!"; exit 1; }
 
# Recreate content dir
rm -r -f content
mkdir content
 
# Copy files from Obsidian vault to content dir
cp -r "$OBSIDIAN_VAULT/"* content/
 
# Build the greatest site!
npx quartz build
 
echo "Sync completed successfully!"

Warning

Dit verwijdert alles uit je content folder. Het is NOOIT de bedoeling dat je hier handmatig bestanden in sleept. Alles wat je er in gooit gaat automatisch verloren.

Site beschikbaar stellen

Ik heb momenteel voor wat andere sites (portfolio & projecten) een VPS. Ik heb hier een nieuw mapje gemaakt in /var/www/ genaamd amiga.pkg-dot-zip.com. Vervolgens heb ik hiervoor een configuratie bestandje gemaakt in etc/nginx/sites-enabled.

Vervolgens heb ik in mijn NameCheap dashboard, waar ik het domein ooit gekocht heb, wat records toegevoegd zodat de site daadwerkelijk te bezoeken is.

Overal 404!

Oh nee, je hebt alles gemaakt maar je kan buiten je hoofdpagina niks meer bezoeken zonder een 404 melding te krijgen! Wat nu? 😭

Kijk goed in de adres-bar van je browser! Staat er .html achter? Zo niet, voeg het even handmatig toe. Als het nu wel werkt ligt het aan je Nginx configuratie.

Je ziet als het goed is een stukje staan vergelijkbaar met onderstaande tekst:

location / {
	    try_files $uri $uri/ =404;
    }

Door een entry toe te voegen met .html suffix kunnen deze wel gevonden worden:

location / {
	    try_files $uri $uri.html $uri/ =404;
    }

Configuratie niet vergeten!

Je moet in de quartz.config.ts de baseUrl property aanpassen naar je (sub)domein.

Synchronisatie

Omdat ik toch bezig ben met automatiseren kan ik net zo goed het bash scriptje uitbreiden om ook te syncen. Ik had in mijn geval liever een apart scriptje hiervoor:

if [ "$#" -ne 4 ]; then
    echo "Usage: $0 <DEST_IP> <DEST_USER> <DEST_PATH> <CONTENT_FOLDER>"
    exit 1
fi
 
DEST_IP="$1"
DEST_USER="$2"
DEST_PATH="$3" # Dest on server.
CONTENT_FOLDER="$4" # Local Quartz content folder.
 
install_rsync() {
  if dpkg -s rsync &>/dev/null; then
    echo 'rsync is installed'
  else
    echo 'rsync not installed. Will install.'
    sudo apt-get install rsync
  fi
}
 
upload_using_rsync() {
    echo 'Attempting upload to server using rsync.'
    local source_folder="$1"
    local dest_path="$2"
 
    rsync -avz --update "$source_folder/" "$DEST_USER@$DEST_IP:$dest_path"
}
 
install_rsync
upload_using_rsync "$CONTENT_FOLDER" "$DEST_PATH"

Graph View