Project Overview: Portfolio Site
I created a writing portfolio project (this page!) using a docs-as-code approach. My goal was two-fold: to establish an online presence, and to get more hands-on experience with docuuentation engineering tools like GitLab, MkDocs, and the like.
Technologies & Tools Used
- Generative AI (Claude and ChatGPT): Ideating, debugging, debugging rant receptacle
- Cursor.ai: Development and CLI
- MkDocs with Material theme: Documentation framework for creating the site
- GitLab: Primary repository for version control, and (soon) CI/CD workflow for publishing
- GitHub Pages: Deployment platform for the live documentation site
- Virtual Environment: For Python dependency management
- Bash/PowerShell: Created aliases for streamlining the workflow
Updates
I created the first version of this site using Cursor to create Markdown files and MkDocs to serve the static site. I used GitLab for version control, and GitHub Pages for hosting the site itself.
At first, I was pushing updates to GitLab, then building the site locally and manually copying the updated site to a separate GitHub Pages directory and pushing it from there as well. I recently implemented Continuous Delivery (CD) to automate the site build and GitHub Pages push, and have also incorporated pre-deployment quality checks to ensure that no links are broken, that the pages all build properly, and that the changelog has been updated.
In terms of the site itself, I started with a basic Material-themed site, and later expanded to include a blog. I've also added plugins for better search, navigation, tagging, and automated timestamping.
Next, I'll look at leveraging releases in Git to better package and track updates, as well as auto-generating changelog entries from commit messages to streamline that part of the process.
Interested in the raw magic? Check out the changelog!