rudolfj.github.io

Rudolf J profile hosted using GitHub Pages.

Staging repo — This repository is the staging (source) repo for the personal website. The built site is deployed to rudolfjs.github.io.

To set up the deployment remote:

git remote add upstream git@github.com:rudolfjs/rudolfjs.github.io.git

Development

Install hugo locally:

Assuming Fedora Linux Version: 42, for other platforms please see Installation.

sudo dnf install hugo

To run the server locally:

hugo server -D --disableFastRender

Creating Content

Use hugo new with the available archetypes to create new content:

Blog Posts

# Structured blog post
hugo new content/blog/posts/your-post-title.md
# Creates a note
hugo new content/notes/posts/your-note-title.md
# Add a project
hugo new content/projects/your-project-name.md
# Add a publication
hugo new content/publications/your-publication-title.md

Code Block Rendering

Control how code blocks are displayed vs rendered using attributes:

Mermaid Diagrams

• ```mermaid - Default: render the diagram
• ```mermaid {.raw} - Show raw mermaid code (syntax highlighted)

Typst Documents

• ```typst - Default: show raw typst code (syntax highlighted)
• ```typst {.render} - Compile and show output
• ```typst {.side-by-side} - Show code and output side by side

Rendering Typst Outputs

IMPORTANT: Typst rendering MUST be done locally before pushing to GitHub.

GitHub Actions does NOT render Typst files. You must generate and commit the PNG outputs locally.

To generate PNG/PDF files for Typst code blocks marked with {.render} or {.side-by-side}:

bash scripts/render-typst.sh

This script will:

• Scan all markdown files for Typst code blocks that need rendering
• Compile them using the Typst CLI to PNG or PDF files (PDF for multi-page documents)
• Save outputs to static/rendered/typst/{page-slug}/typst-{hash}.png or .pdf
• Cache previously rendered files (won't re-render if unchanged)

Image inputs: Images referenced from Typst code with bare relative paths (e.g. image("tree.jpg")) live in assets/typst/. The render script copies them into its temp compile dir by basename so those paths resolve. Put any new Typst image inputs there. (references.bib is still read from the project root.)

Content Publishing Workflow

For posts with Typst rendering:

1. Create or edit your markdown file:

   hugo new content/notes/posts/my-new-post.md
   # Edit the file, add Typst code blocks with {.render} or {.side-by-side}

2. Generate Typst PNG/PDF outputs:

   bash scripts/render-typst.sh

3. Test locally:

   hugo server -D
   # Visit http://localhost:1313 and verify your content renders correctly

4. Commit and push:

   git add content/notes/posts/my-new-post.md
   git add static/rendered/typst/my-new-post/
   git commit -m "Add new post with Typst rendering"
   git push

For posts without Typst rendering:

1. Create/edit markdown file
2. Test locally with hugo server -D
3. Commit and push

Important Notes:

• REQUIRED: Render Typst locally before pushing - GitHub Actions does NOT have Typst installed
• Always commit the generated PNG/PDF files - They must be in the repository for GitHub Pages to serve them
• The render script uses caching - only re-renders changed content
• Raw Typst code blocks (```typst) don't need the script, they just show syntax-highlighted code
• Mermaid diagrams work without scripts (rendered client-side)