How this site is built, step by step, so anyone can build their own. The whole thing is plain files: Markdown for the words, Astro for the templates, GitHub Pages for the hosting.
- 01.
HOW TO WRITE THE BRIEF
Start with one plain-text file, PORTFOLIO_BRIEF.md, that lists every verified fact: roles, dates, counts. Every number on this site must trace back to that list. If a fact is not there, the page says so instead of inventing one.
- 02.
HOW TO INSTALL THE TOOLS
Install Node.js, then run npm install once inside the project folder. That pulls in Astro, the static-site framework, and nothing else. There is no database and no server to manage.
- 03.
HOW TO RUN IT LOCALLY
Run npm run dev and open http://localhost:4321. Every saved file refreshes the page. Close the terminal and the site is gone; nothing is published until you build and push.
- 04.
HOW TO ADD A CASE STUDY
Add one Markdown file to src/content/work/. The top of the file holds fixed fields (title, tracks, featured, order, date, timeline, role, audience, constraint, outcome, tools, images); the body holds the story. The file name becomes the URL.
- 05.
HOW TO TAG AND FILTER
Every case study carries one or more of five tracks: design, presentation, data, ai, leadership. The Work page reads ?track= from the address bar, so /work/?track=data is a link you can send to one employer.
- 06.
HOW TO LEAVE A NOTE TO SELF
Write TODO(Matt) at the start of a paragraph and the site prints it as a mono "NOTE TO SELF" line instead of broken copy. Any page that still has one wears a striped "WORK IN PROGRESS" band. Unfinished, but honest.
- 07.
HOW TO EXPORT FROM FIGMA
The old portfolio lived in Figma. scripts/figma_export.py, with a personal access token, pulls every image and text layer out of that file into a folder, so nothing has to be rebuilt by hand.
- 08.
HOW TO LABEL THE OBVIOUS
The look is browser defaults edited about three percent: white paper, black ink, one 1px rule, uppercase labels in straight quotes, mono for anything that reads like a receipt. All of it lives in two files, src/styles/tokens.css and src/styles/global.css.
- 09.
HOW TO SHOW THE GRID
Press the "SHOW GRID" button in the masthead, or the G key, and every layout region gets an outline and its name. Nothing is hidden; the construction is part of the design.
- 10.
HOW TO BUILD
Run npm run build. Astro turns every Markdown file and page template into plain HTML in a dist/ folder. The footer receipt prints the build date and the page's JavaScript weight from that run.
- 11.
HOW TO DEPLOY
The repository is named exactly mjzun.github.io, so GitHub Pages serves it at the root URL for free. A GitHub Actions workflow rebuilds and publishes on every push to main. A custom domain later is one CNAME file.
- 12.
HOW TO REUSE THIS
Clone the repository, replace the files in src/content/work/ with your own case studies and src/content/site.json with your own facts, then run npm run build. The method is public; the facts have to be yours.
STACK
- FRAMEWORKASTRO
- CONTENTMARKDOWN, ONE FILE PER CASE STUDY
- STYLESTWO CSS FILES, NO FRAMEWORK
- SCRIPTSFIGMA_EXPORT.PY
- HOSTINGGITHUB PAGES
- SOURCEgithub.com/mjzun/mjzun.github.io ↗