nicholassynovic.github.io

Nicholas M. Synovic's website is built with Sphinx and deployed to GitHub Pages.

Current Status

• Active documentation website project using Sphinx + uv
• CI deploys the site from main using .github/workflows/build.yml
• Validation is centered on pre-commit checks and Sphinx build verification

Production URL

• https://nicholassynovic.github.io/

Repository Structure

• src/: Sphinx source files (.rst, conf.py, static assets)
• src/_static/: custom CSS, images, and document assets
• src/blog_posts/: blog post pages
• src/papers/: publication pages
• build/: generated site output (artifact/output directory)
• .github/workflows/build.yml: CI build and deploy workflow

Prerequisites

• Python 3.13 (project target)
• uv
• make (optional convenience commands)

Quick Start

uv sync
make build

Open build/index.html after a successful build.

Build and Preview

Build docs:

make build

Equivalent direct command:

uv run sphinx-build -vvv --write-all --fresh-env src build

Live preview during edits:

make serve

Equivalent direct command:

uv run sphinx-autobuild src build

Validation Before Opening a PR

Run formatting/lint checks:

pre-commit run --all-files

Run build validation:

make build

How to Contribute

1. Review contribution policy in .github/CONTRIBUTING.md.
2. Create a feature branch from main.
3. Make focused changes in src/ (and src/_static/ when needed).
4. Run the validation commands above.
5. Open a PR with a concise rationale and verification notes.

Step-by-Step: Add or Edit a Blog Post

1. Create or update a .rst file in src/blog_posts/.
2. Follow existing blog post structure and metadata patterns.
3. Ensure the post is listed from src/blog_posts/index.rst as expected.
4. Build locally (make build) and verify rendering.
5. Run pre-commit run --all-files before opening the PR.

Step-by-Step: Add or Edit a Paper Page

1. Create or update a .rst file in src/papers/.
2. Follow existing paper page structure and citation conventions.
3. Ensure the page is discoverable from src/papers/index.rst.
4. Build locally and verify the page renders correctly.
5. Run pre-commit checks before submitting the PR.

Step-by-Step: Update Website Styles

1. Edit src/_static/custom.css.
2. Prefer scoped style changes over broad global overrides.
3. Verify desktop and mobile rendering.
4. Rebuild and confirm no regressions in core pages.

Sphinx-Specific Authoring Notes

• Preserve heading hierarchy and adornment style within each .rst file.
• Reuse existing directives and patterns used by nearby pages.
• Keep prose concise and avoid redundant sections.
• Keep links explicit and confirm they render correctly in the built site.

Release Process

This project supports two release tracks.

1) Website release (deployment)

• Merge the approved PR to main.
• GitHub Actions builds and deploys the site via .github/workflows/build.yml.
• Confirm the production site reflects the new content at https://nicholassynovic.github.io/.

2) Versioned release (SemVer tags)

1. Ensure the desired changes are merged to main.
2. Create and push a semantic version tag, e.g. v1.2.3.
3. Create a GitHub Release for that tag.
4. Draft release notes from merged PRs and resolved issues since the previous tag.

Contribution Guidelines

• Contribution process: .github/CONTRIBUTING.md

Privacy Notice

This site uses Google Analytics (GA4) to collect aggregate usage insights.

• Measurement ID: G-0Y7Y4XLQHD
• Script source: https://www.googletagmanager.com/gtag/js?id=G-0Y7Y4XLQHD

Tracking Behavior

• Analytics is loaded by default on page load.
• Page usage is measured via the GA4 tag.

Managing Data

• You can block analytics requests using browser privacy controls, script blockers, or network-level filtering.
• You can clear site data and cookies through your browser settings.

Agent Guidance

• Agent-specific repository rules are documented in AGENTS.md.
• Recommended model: GPT-5.3-Codex in GitHub Copilot.