2. Project management¶

Fab Academy has kindly provided a boilerplate site to build upon which I intend to use. We have the option to completely remove it and create the site in what ever way we seem fit.

The site is built using MkDocs and hosted on Gitlab and published using continuous integration.

Personally I’m a big fan of this setup. I’ve used a similar framework, Hugo, but testing a new thing is always fun.

I really like the concept of a site generator. It’s a great way to create a site that is easy to maintain and update. They may not be suitable for all purposes, but I think it’s a great way to documents project and create sites that should be rather lightweight. It’s ideal getting your information and content from your mind to the site, without having to worry about formatting and other technical stuff.

Customization¶

I’m not really much of a designer and sadly I have to plan my time carefully, so I was not able to spend much time to completely redo the site. BUT! There are a few things that I can do and must say!

I find the default layout and setup to be very nice. But there are a couple of things that I just had to do:

Minimize eye strain! Staring at a computer screen all day is difficult enough for the eyes, enabling dark mode is something people should do more.
Adding a bit of color-contrast.

Luckily, this is a breeze with MkDocs. In MkDocs, you edit the mkdocs.yml and modify the settings. Check out the documentation here!

To see the changes I did, we can simply check the history within my repo! Magic!

You can see the actual change here.

The red text shows what I deleted from the file and the green part is what I added.

So to enable the dark mode you have to add scheme: slate under the palette part of mkdocs.yml. This is the name for dark-mode in MkDocs. Then just tune the primary and accent colors to your liking!

Wonderful!

Environment - physical & virtual¶

Currently I have two offices, using a laptop and a desktop. I also have a virtual machine running Ubuntu. At home I either use my work laptop or my wife’s MacBook. So my work is spread all over the place and I use whatever operating system fits as they all have their up- and downsides.

When using multiple computers at different locations, proper tools become an extreme necessity. So, a quick overview of the setup:

Git for version control
MS-Onedrive for all things sync (provided by employer)
Syncthing for work related to and within the Fab Lab Akureyri
Fusion 360 projects sync to the cloud
Shared folders/drives between Windows host and Ubuntu virtual machine
VSCode for text/code editing

Setup¶

I already had Onedrive, Syncthing and the Ubuntu virtual machine with share running. I also have most of the tools needed for the Academy installed, although I have yet to experiment with some of them, mostly regarding the electronics design/manufacture.

I have used Git before, both terminal and GUI(ex: GitKraken) but I plan to stick to the terminal during the Academy.

ssh-keygen¶

For my work and other project, I already had ssh-keys generated. I have used ssh-keygen to generate the my keys, both on work (windows) and private (Ubuntu/macos) computer so adding them to my Fabcloud profile was trivial.

But if you are reading this and need to generate your own keys, you can do so by running the following command:

ssh-keygen -t rsa -b 4096

-t stands for type, rsa is the type of key you want to generate. -b stands for bits, 4096 is the number of bits you want to generate.

The command should suffice for most normal usage but if you’d like to dive deeper, you can check out the ssh-keygen man pages. If you are unfamiliar with the terminal (linux/mac), the man command is for reading manuals for all sorts of things. The manuals are also available online and they contain a wealth of information.

If you are using Windows, here is a good guide.

Once I got access to fabcloud/gitlab I started to make sure the software was in working order. I updated software, such as Python to 3.10.2, found out that git bash does not work properly while using Git in command prompt and in the VSCode terminal works perfectly fine. After adding SSH keys to my gitlab account I started to checkout the repo.

Cloning the repo:

git clone https://gitlab.fabcloud.org/academany/fabacademy/2022/labs/isafjordur/students/arni-bjornsson''

After installing MkDocs I tried serving the site but errors were thrown:

Running the following fixed the missing items and the page was served properly:

pip install mkdocs-material
pip install mkdocs-git-revision-date-localized-plugin

I began by updating the mkdocs.yml file, testing the CI and once all figured out and working properly I started work on the page itself.

My workflow¶

This part is added a few weeks into the Academy.

By now, I have settled into a nice rhythm of working on the page and making sure it is up to date. Let’s go over my current workflow and setup.

I mostly use the two Windows computers provided to me by my work. I use Visual Studio Code to work on the site. VSCode includes a terminal, where I issue my git commands.

A good habit when starting is to check if the local repo is up to date. To do that I use git status and git pull.

The former tells me if there are any changes in the local repo, the latter updates the repo to the latest version in case I have made modifications elsewhere.

Content¶

Image management¶

In the Fab Lab I have a camera that I dedicate to this work. I regularly dump its content to a Onedrive folder, with the intent to keep the originals in case I need them later.

From there, I select the images I need to my current week and copy them over to the images folder within the repo. There, I right click them and using the PowerToys for Windows, select resize to shrink them. I then rename them individually to fit sections of each week.

This allows me to have a clean repo with all the images I need, conserving space on the host (Fabcloud) and still keeping all of the originals safe and secure.

Writing content¶

As mentioned before, I edit the site using VSCode and I use Markdown to write the text. This is what my screen often looks like:

There I have the ide on the left and a browser on the right. When I issue the command:

mkdocs.exe serve

I get a live-reloading site running on localhost. That means I can view the site live, just like it would appear on the interwebs. When I make a modification and save it, the preview is updated.

Once I have finished writing and adding what ever files I need I run git status to see what needs to be done and I might be faced with something like this:

It tells me I have modified two files and that I three new files to the repo. I then run:

git add docs/images/week02/*

This adds all the files within the image folder of week02 to the commit. If you are not familiar with the * wildcard/Kleene star, it means that all files within the folder will be selected.

Next I would run a command like this:

git commit -m "Added images for week02"

You can view commits as kind of a save-points. You can revert to a previous commits and do all sorts of fancy stuff with git but I will not go into that here and now.

Once you are happy, you can push the changes to the repo. To do that you can run:

git push

This will push the changes to the remote repo. In our case, on Fabcloud, that will trigger a new build of our site. On Fabclouds servers, the MkDocs program and other tools build, copy and publish the site. Magic!

A personal pet peeve¶

I really like to have captions below images. Maybe I like captions too much, but they are something I feel compelled to add.

In MkDocs, adding an images is usually done like this:

![Alt text](../images/week02/image.jpg)

The alt text is the text that is displayed when the image is not visible or when the user hovers over the image. It is also extremely important for screen readers. But for me, the alt text is not displayed when hovering so it pretty much fails it purpose in my view. So I found that I can use this command:

<figure markdown>
  ![Alt text](../images/week02/image.jpg)
  <figcaption>Alt text</figcaption>
</figure>

There maybe a better way, but it works well for me. It’s a quick copy and paste job and I believe it adds a lot of value.

To sum up¶

Syncing stuff is awesome, git is awesome, static sites with CI are awesome, everything is awesome!

Last update: March 29, 2022