Skip to content

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:

  1. This one: blog.nicfv.com - now nicfv.com/blog
  2. My photography website: photos.nicfv.com
  3. 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.

Minor Differences

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.

Portfolio

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:

YAML
1
2
3
4
5
6
7
# mkdocs.yml
plugins: []

# index.md
hide:
  - navigation
  - toc

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:

Markdown
1
![Me](me.jpg){ style="max-width:200px;height:auto;float:right;" }

Blog

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.

Photography

By far this was the most complicated development. First I need to describe my planned process of maintaining this website:

  1. Take a new set of photos
  2. Create a new folder in my website directory that follows the pattern: YYYY/MM/Location
  3. Dump my photos in the new folder
  4. 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!