portfolio-pages

Live site: michaelj43.dev · GitHub Pages default URL (project path)

---

What this repository is for

This repo is a personal portfolio published on GitHub Pages. It gives a short overview and, for each highlighted GitHub project, a brief write-up (about two sentences) with a link to the source repository. Content is data-driven so you can refresh copy without touching the generator logic.

How the site is built

The published site is static HTML and CSS.

Piece	Role
content/repos.yml	Intro, links, and one block per repository (title, URL, optional language tag, summary).
src/sitegen.cr	Small Crystal program: reads the YAML, renders templates/index.ecr (ECR templates), writes dist/index.html, copies public/ (e.g. styles and .nojekyll) into dist/. Stylesheet uses a relative styles.css URL so the same build works for a custom domain at the site root, the default *.github.io project URL, and PR preview subpaths.
public/styles.css	Layout and light/dark-friendly styling.

Building the generator takes the Crystal compiler (stdlib only for this code). shard.yml holds the project name and semver for metadata.

Deployment flow

1. Push to main triggers .github/workflows/deploy.yml.
2. Install Crystal with crystal-lang/install-crystal (version pinned in the workflow to a real Crystal release tag).
3. Compile the generator: crystal build --release src/sitegen.cr -o bin/sitegen.
4. Run ./bin/sitegen to write dist/ (no base-path env: CSS is linked with a relative href so it resolves correctly for custom domains, project Pages URLs, and previews).
5. Publish the dist/ folder to the gh-pages branch using peaceiris/actions-gh-pages (keep_files: true merges with existing branch content, e.g. PR preview folders).

Pull requests: .github/workflows/preview.yml publishes the same build under preview/pr-<N>/ on gh-pages, comments the preview URL on the PR, and removes that folder when the PR is closed.

Repository settings: In GitHub Settings → Pages, use Deploy from a branch → branch gh-pages, folder / (root). Optional variable: CUSTOM_PAGES_URL (see CONTRIBUTING.md) so PR preview links use your custom origin when set.

Run it locally

Dependencies

Dependency	Why
Crystal (1.11 or newer; CI uses 1.19.1)	Compiles sitegen.
Python 3 (stdlib only)	Optional but convenient: http.server to preview dist/ in a browser. Any other static file server works.

Commands

From the repository root:

mkdir -p bin
crystal build --release src/sitegen.cr -o bin/sitegen
./bin/sitegen
python3 -m http.server --directory dist

Then open http://localhost:8000 (or the port shown in the terminal).

Environment variables (optional)

Variable	Default	Purpose
CONTENT_FILE	./content/repos.yml	YAML source for copy and repo list
DIST_DIR	./dist	Output directory
PUBLIC_DIR	./public	Static assets copied into dist/

---

Contributing

Use feature branches and PRs into main. Details on preview URLs and repository variables are in CONTRIBUTING.md.

Versioning

Bump the semver in shard.yml when you ship meaningful changes to the generator or site layout.