Personal Website - Moritz Boos

This is my personal website built with Sphinx and MyST Markdown, deployed to GitHub Pages.

Live site: https://mjboos.github.io

About

This site includes:

• Blog: Posts about Python, machine learning, neuroscience, and data science
• Publications: Academic publications and preprints
• Projects: Open source projects and tools

Technology Stack

• Static Site Generator: Sphinx with MyST-NB
• Theme: PyData Sphinx Theme
• Blog: ABlog
• Package Manager: uv (fast Python package installer)
• Deployment: GitHub Actions → GitHub Pages

Building the Site

Prerequisites

• uv (recommended, 10-100x faster than pip)
• OR Python 3.11+ and pip

Installing uv

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

With pip:

pip install uv

See uv installation docs for more options.

Local Development with uv (Recommended)

1. Install dependencies:

   uv sync

   This creates a virtual environment and installs all dependencies from pyproject.toml.

2. Build the site:

   # Build with uv run (recommended)
   uv run sphinx-build -b html . _build/html
   
   # Or use nox
   uv run nox -s docs

3. Live preview (with auto-reload):

   uv run nox -s docs -- live

   This will open the site in your browser at http://localhost:8000 and automatically rebuild when you make changes.

Alternative: Using pip

If you prefer pip over uv:

pip install -r requirements.txt
sphinx-build -b html . _build/html

Note: You may encounter installation issues with ablog (specifically with feedgen). If so, try:

pip install --no-build-isolation ablog

The built site will be in _build/html/.

Project Structure

.
├── blog/              # Blog posts organized by year
│   ├── 2020/
│   ├── 2021/
│   └── 2022/
├── _static/           # Static assets (CSS, images, etc.)
├── _templates/        # Custom Sphinx templates
├── conf.py            # Sphinx configuration
├── pyproject.toml     # Project metadata and dependencies
├── uv.lock            # Lockfile for reproducible builds
├── .python-version    # Python version specification
├── index.md           # Homepage
├── about.md           # About page
├── blog.md            # Blog index
├── publications.md    # Publications list
├── projects.md        # Projects list
├── requirements.txt   # Python dependencies (for pip compatibility)
└── noxfile.py        # Build automation

Adding Content

New Blog Post

1. Create a new markdown or Jupyter notebook file in blog/YYYY/ (where YYYY is the year)
2. Add frontmatter:

   ---
   date: "YYYY-MM-DD"
   author: Moritz Boos
   tags:
     - tag1
     - tag2
   ---
   
   # Post Title
   
   Content goes here...

New Jupyter Notebook Post

Simply place a .ipynb file in blog/YYYY/ with appropriate metadata. The notebook will be rendered directly.

Managing Dependencies

Dependencies are managed in pyproject.toml under the [project] section.

Adding a New Dependency

1. Add the package to pyproject.toml:

   [project]
   dependencies = [
       # ... existing deps
       "new-package>=1.0",
   ]

2. Update lockfile and install:

   uv lock
   uv sync

Updating Dependencies

# Update all dependencies to latest compatible versions
uv lock --upgrade

# Update a specific package
uv lock --upgrade-package sphinx

# Install updated dependencies
uv sync

Compatibility Note

requirements.txt is kept for backward compatibility with pip users, but pyproject.toml is the source of truth.

Deployment

The site is automatically deployed to GitHub Pages via GitHub Actions when you push to the master branch.

The workflow is defined in .github/workflows/deploy.yml.

Configuration

Main configuration is in conf.py. Key settings:

• Extensions: myst_nb, ablog, sphinx_design, sphinx_copybutton, sphinxext.opengraph
• Theme: pydata_sphinx_theme
• Blog settings: Post pattern, feeds, excerpts
• Notebook execution: Currently set to "off" (change to "cache" to execute during build)

Migration Notes

This site was migrated from Jekyll to MyST+Sphinx. See MIGRATION_NOTES.md for details.

License

Content is licensed under CC BY 4.0.