The birth of my 3 'main' websites
Hello, world! This is my first post on this website, although I may retroactively add some prior work. Today I had time to work on my own projects, and I finally knocked this one out of the way. Today marks the birth of my 3 'main' websites. Those being:
- This one: blog.nicfv.com - now nicfv.com/blog
- My photography website: photos.nicfv.com
- And, my homepage: portfolio.nicfv.com (or nicolasventura.com)
At work, I recently learned about a technique to generate beautiful documentation using a software package called
mkdocs. I immediately started playing around with it and discovered it can be used for so much more than code documentation. As of this article, all 3 of my mentioned websites are using
mkdocs to build the website.
How does it work?
mkdocs takes input markdown files and generates a HTML and CSS code package that can be hosted at any modern web hosting service. GitHub Pages is a good solution, since it is free, and I am just generating static pages. The input markdown files can be extended to also include custom HTML and CSS, but unless you are trying to do something very specific, it's usually not necessary.
It also requires a "theme." There are a few builtin themes in
mkdocs but there are several professional-quality themes that are built and maintained by the community. My favorite theme by far is
mkdocs-material because of its extensive configuration options. I am using the same theme with similar configuration for all 3 of my websites. Notice its versatility, going from a blog, to a photography website, to a single-page portfolio.
Each website had its own complications associated with building it initially. For each one, I had to set up a corresponding
mkdocs.yml configuration file for
mkdocs, and a
.github/workflows/pages.yml workflow file to automatically stage, build, and deploy each website on every commit. Each of these files had minor (or major) differences going from one website to the next.
By far, this was the simplest configuration to implement. My goal was to remove the top bar entirely, but unfortunately this was not possible without additional CSS. (I wanted to avoid custom CSS to ensure not to overwrite any of the CSS rules generated by
mkdocs.) However, I found it possible to remove the search bar, navigation bar, and table of contents, simply with this bit of YAML:
The only other oddity in this setup was the profile image the Download Resume button. For both of those, I had to go against my previous statement and use custom CSS. Instead of including an entire stylesheet, I entered the style rules directly in
index.md using CSS selectors. This was made available by the
attr_list extension. Here is my profile picture, as an example:
For this one, I had to install the
blog plugin from
mkdocs-material. At this point in time, it's not a full-fledged feature yet, so it is only compatible with the latest beta version of
mkdocs-material. Unfortunately, the beta version of
mkdocs-material takes about twice as long to install in the GitHub workflow (from about 10 seconds to 20, so not a huge issue.) The
blog plugin also expects a different file structure by default, so I had to add some configuration to indicate which directory my blog posts are in, as well as additional configuration for the navigation dropdown menu.
By far this was the most complicated development. First I need to describe my planned process of maintaining this website:
- Take a new set of photos
- Create a new folder in my website directory that follows the pattern:
- Dump my photos in the new folder
- Rename the photo files to set their captions
In this process, I do not want to create any markdown files manually. I created a Python script to search for all image files and generate an entire package of markdown files to use in the website and execute
mkdocs. This Python script carefully does not package any image files into the final website structure. Why? Each image is 1-10MB. Currently there are over 60 photographs on my website, still early in development. Taking an average case of 5MB per file, that makes 300MB total, or about 1/3 GB, not including any other files!
Originally, my Python script packaged all images in the website. I realized this was unsustainable early on, when the GitHub workflows were taking over 5 minutes just to upload the website! After I made the change to ignore the images, the total process start to finish takes around 30 seconds to 1 minute only!
But how does the website still render the photographs at all? I marked that GitHub repository as public, which means the files are publicly hosted for all to see. I modified the script from referencing local image files, to remote-hosted files, from my GitHub repository. Surprisingly, this actually made my website load even faster! Thanks, GitHub!