Week 1: Principles and Practices and Project Management

##ToDo this week

Do a git tutorial Neil suggested this one. ✅
Sketch and describe a final project idea. ✅
Build a person website. ✅
Document the process. ✅

Starting Early

As soon as I had my GitLab account I started messing with my site. This was during the student bootcamp week. My initial efforts are described on my Week 0 Page.

Git

I skimmed through Neil’s suggested git tutorial but found it to focus on a lot of commands that I didn’t actually need for this project. This is most of what I will need.

#normal commit
git status
git add <files to add>
git commit -m "<Commit message>"
git push

#pull changes if I use the web editor
git pull

I’ve added a bit more below about adventures in submodules and removing outdated stuff. I also played with branching when I changed which website generator to use. I saved a branch with my mkdocs setup incase the switch to hugo didn’t go well. This isn’t strictly necessary as I could have just rolled back the history in the master branch but I wanted to play with branching.

Ditching MkDocs

After looking around at a lot of former student websites I decided that I didn’t like the look of mkdocs and I wanted to try something else. I didn’t want to work in straight html and I like working in markdown from the little bit I’d done in mkdocs. Though I need to figure out how to enable spell check in macDown or whatever mark down editor I end up using long term (I’ve since started using Atom which has spell check). Kris from Aalto FabLab had suggested that we look at his youtube tutorials for using Hugo, another static site generator that seems to be more powerful than mkdocs.

It took a bit more to wrap my head around it. The getting started documentation assumes a lot of knowledge but I’m used to that from working with open source software before. I found a Hugo theme that I liked and gave it a go. I ran into a lot of problems getting the initial site to show up that mostly came down to copying the config.toml file from the example site into my test site. Once I had that figured out I could just copy in my markdown files from mkdocs and everything just about worked. I’m sure I’ll have some more work to do to pretty them up over the next few days but this looks way better than mkdocs to me so I’m happy with it.

Diving into Hugo

Getting Hugo installed locally was a breeze. That is one of its primary features, single binary with no dependancies, and if you’ve ever been stuck in dependency hell you know how big of a deal that is. I of course ruined it by choosing a theme that has some fancy features with some external dependancies. No matter the theme’s homepage gives two npm modules to install. Fortunately this isn’t my first rodeo so I knew to use brew to install npm.

brew install npm
npm install -g postcss-cli
$ npm install -g autoprefixer

I was off to the races… or so I thought. I made a hugo skeleton site. I tried to clone the theme git repository but was getting a strange error that there was no repository at the given url even though I tried copying it from the theme readme and directly from the theme github page. No matter I just downloaded the zip file and carried on. I then added the theme to the config.toml file and hit an error saying that paginator_pages had to be a number greater than 0. Googling this error message was unhelpful. One of the problems with using these pre-built themes is that your adding a bunch of code with basically no manual or support documentation. Which was probably a bit ambitious to do on top of a site generator that I know nothing about. After a bit of flailing, I found the mystery parameter in the config file of theme’s example site. I still didn’t really understand what it did but I picked a number and added it to my config and I was up and running.

Customization

I know just enough html, css, and javascript to be dangerous, and I’m pretty good at skimming code for keywords that look helpful. Once I got my markdown files from mkdocs copied into the content structure of hugo I wanted to change the look a bit. I liked that the theme had a switcher between a light and dark theme. Click the sun/moon icon in the top right corner. However the light theme was the default, I prefer the dark. I dug through the file structure of the theme and found switch.js which is a single line file but its a very long, dense line. Not quite obfuscated code at its finest but getting there. I parsed it enough to figure out that it checks to see if there is a stored cookie with a light/dark preference and if there is no stored key default to light. I switched that to dark and job done. Next the theme had a bunch of extra features in the navigation sidebar that I didn’t want and it didn’t have a table of contents for the current page which I did want. It took me a while to realize that table of contents was the key search term I needed. Once I knew to look for that it was pretty simple to add it. Hugo’s Docs page as well as this youtube playlist were very helpful in getting the basics of how hugo works.

Publishing

I still have a bit of work to do on the css to get things looking just how I like them, but this is close enough that I’m committed to it and I need to push it up to gitlab and figure out the continuous integration script to get it published.

Dependency Hell

Oh boy did I underestimate what I was getting into. As previously stated one of Hugo’s big selling points is no external dependancies. I then went and chose a theme that required some Node.js modules as part of the fancy javascript stuff. Not that I actually needed that functionality, I just like the look of the theme pages. Once I committed all of my updated theme, config, and markdown files to git lab I was rewarded with the pipeline failing. The Blonde theme docs told me I needed two modules installed with npm so I tried to add the npm install commands to the gitlab-ci.yml file only to get an error message saying the docker didn’t know what the npm command was. This lead me down a docker rabbit hole. I know that a docker is a lightweight linux virtual machine and I read on the GitLab pages documentation that told me its pulling images from Docker Hub. I looked into the hugo docker image which looked like installing extra software into it would be complicated. I thought briefly about creating my own fork of the docker image and adding the software I needed but decided that I was already far enough down the rabbit hole. Instead because of hugo’s simplicity I decided to try a yml file template meant for a Node.js project meaning that it would have npm ready to go and then add hugo to it. After much gnashing of teeth I did get that to work. I had to reference the example site and pull its package.json file which is a list of npm modules to configure. I did a small Node.js project last spring and learned just enough to remember that was probably important. Once i got this new pipeline to build successfully I at least got a page to display from gitlab but something in the build was still wrong. All the URLs hugo generated were built with the gitlab build environment as the base URL instead of my gitlab page. This meant that the home page had no styling and all the links were broken. After fighting with it all day Sunday I gave up and decided to pick another theme. I quickly grabbed the first theme I vaguely liked from the Hugo themes list that didn’t require any dependancies and loaded harbor. I pushed this to GitLab and fixed the ci file to be a normal hugo site and it worked right away. 😥

Taking another stab

Now that I know my limits I still need to make this page actually look good. I found another theme that I liked called zzo. I took a bit of time to test this out locally and get things the way I wanted them. I was very appreciative that this theme actually has its own documentation page in addition to hugo’s docs so I’m less confused going back and forth between what is a theme setting and what is a hugo setting. I got things working while listening in to the recitation on git and checking in with my fellow Dassault Systemes students at our first office hours. Once I was happy with things locally I needed to push it up to GitLab which is what gave me so much trouble previously. First I had to clear out all the old junk that I wasn’t going to use anymore. I had a few hiccups getting confused by using git rm on some files and deleting them from the GitLab website on other things. Once I had pushed and pulled in the right order and sorted the repo back down to just my content and a bare hugo skeleton I started to copy in my updated content and add the new theme.

I didn’t realize what I was doing at the time but when I added the quick test theme at the end of my long day the instructions suggested adding it as a git submodule. This is a cool feature which I don’t fully understand but I noticed that when the ci script runs it gets checked out from upstream instead of using the local version from my repo. I’m not sure if this actually saves space in my repo and it seems like it might introduce the potential for it to break my build unexpectedly at some point in the future but its cool for now. This meant that when I went to remove the theme it was slightly more complicated. I found this helpful post that made it straightforward. I had to removed it from the .gitmodules file, remove references to it in .git/config, run git rm with the –cached flag, then delete the files locally, and commit that change. I also took this chance to add a few things to my .gitignore file that seemed like temp files that hugo was leaving behind from running its local webserver.

The last hurdle

Once I had the new theme, content, and supporting files all in place and pushed to gitlab I was greeted by an all too familiar pipeline failed icon. Looking at the pipeline output there was a very useful error message that I needed the extended version of hugo, which suprised me because I didn’t think I was running the extended version on my laptop but I just got whatever brew installed and I never checked. I also later found in the documentation for the theme that it says it needed hugo_extended, should have RTFM. Fortunately I had done enough digging into the docker images in yesterdays debuggging that I was fairly sure that there were docker images that had hugo_extended all set up. I found the path in the GitLab pages container registry and replaced the default image path with the path to the hugo_extended image. Pipeline success. Webpage displays correctly. Happy Dance time!

Still pending

There’s still a few things I need to clean up. I’m not sure why the list of posts on the homepage or assignments list are not appearing in order. Hugo is supposed to follow the weight tag that I placed in each markdown file and if not that then the date tag which is also in each file. I’ll have to keep digging on that. There is also a showcase feature on the theme which I would like to use instead of the listing of posts for the homepage. I’m still working that out, but this will do for now.

Post Ordering

2/13/21
I finally read through the page weight documentation and I found that weight 0 means no weight and therefor ordered last. This was actually the only page appearing out of order. So I re-weighted all my pages in their front matter and the order is correct now.

Final Project Sketch

This page is getting long I have made a separate page in the final project section for the planning sketch.