Week 1; Project management

The first week is all about setting up a site for the documentation of the FabAcademy. Starting with learning about a static site and finding out about the system of Gitlab.

Weekly Assignment

In my own words

this week we have two assignments:

• Work through a git tutorial
• Build a personal site in the class archive describing you and your final project

My starting point is virtually no knowledge of Git and I once did build a very simple static site with HTML/CSS more than 10 years ago.

So my goals for this week are to get the Gitlab connection working and to build a simple website with a theme as base.

Planning this week

Learning activities; introduction to the subject

To start with I looked at all the links from the presentation and I got totally lost. There is so much information and I don't know how to choose.

Tutorials and Youtube

gitlab

What did I learn:

Watching the set of tutorials I learned about the concept of git and the basic functionality.

I learned that you can work on your local computer on a clone of the repository that is online on the Gitlab-server. But it is not automatically connected. If I want to upload the changes you make locally I'll have to do a push, and if I (or anybody else) made changes to the online version that are not yet on my local clone on my laptop I have to do a pull. In order to have these connections I will need a SSH-Key (a combination of a public key that is on the server and a private key on my laptop that matches the public one)

Static websites generators.

How does the making of a website work:

If I will use a static site generator the website is split up in 3 pieces:

• The theme (visual and structural setup of the file)
• The static files (for example images)
• The markdown files (with the text and the links to the images and external sites) These last 2 together, are called the the content.

The static site generator combines these three parts and with that it can build a static HTML-site.

HUGO

Mikes HUGO tutorials are great he really explains everything in small bits and pieces. IN a combination of a site with the idea written out and a video that explains it in words. Real online workshops

Mike Danes HUGO tutorial

First Experiments and results

MKDocs, Jekyll and HUGO

I was having a lot of trouble working with MKdocs and could not get to change anything in the themes. (eventually we found out that by installing MKdocs with Homebrew, something went wrong and it was not able to download different themes.) I did understand the basics though, And the first small changes I made in the repository I did with MKdocs but the limited differences in the downloadable themes and the fact that I could not download them made me choose for something else. Jekyll looked very complicated, especially since you had to download Ruby and only after that Jekyll would work, so I figured, let's find out about HUGO. several co-students are using it and some also have some experience, that could be handy. And the amount of themes looked like it would be great to work with.

Gitlab SSH key cheatsheet

Together with the whole group I set up the SSH key, for that we used the SSH-key cheatsheet that was in the Gitlab tutorial section. Nadieh was experienced and with her coaching we all got it done.

Clone of the repository

So now I have the whole connection set up and I want to clone the repository to my laptop so I am able to change things. First get the right clone from the gitlab repository (the SSH-one) and then go within terminal to the right directory and use the following code to make a download of the directory that is connected:

1git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/waag/students/lucia-jonkhoff.git

Themes and struggles with that

The idea of using HUGO was for me that I could easily start with a theme that I could find online and just alter the content. In practice it did not work for me that way.

Bare Minimum

The basic idea that I have for my website has a top menu bar where I can put the The main links of the different parts of the site (the about me, the weekly assignments and the final project) on the left I would like a menu-bar where I can show the different weeks that I documented and a separate part about the final project and the different pages about that.

Failures and learnings

What went wrong and how did I fix it and learn

Learningprocess

First of all I had no idea that we were going to make our own site on a gitlab-site. so this all was very new to me. I would have been wonderful if I had this knowledge prior to the Bootcamp-week. Now the different information came to me as loose bits and pieces and I was trying to keep up without knowing why I was downloading the different things. On thursday I realise that if all these loose bits are the way that we will get the information to us, I will have to find my own way to structure it. This bootcamp-week would make more sense to me if I would have a preview in the things that are expected from us. So I did a preview of the Principles and Practices video and the project management video (the ones from last year).

With that I accomplished 2 things:

• Finally could put together wat we were doing and learning during the bootcamp
• the amount of information was very dense, so with the preview and looking at the links and extra information I got that way, it was much clearer for me the second time when I watched the 2021 global meeting.

So my learning is for every week is to preview last years global sessions and recitations so

1. I know what we are about to do
2. I am not so overwhelmed with information during the 2021 live-eventually

Practical

So the first thing that went completely wrong was the set-up of MKdocs. By installing it through Homebrew (a program that I installed minutes before MKdocs) it did not work properly and I could not even get through the online tutorial that was on the MKdocs-site. I tried different tutorials and asked people about how I should do it, but nothing seemed to work. So I concluded that I did something wrong but I could not figure out what. This cost me a lot of time and energy. Two days later I found out during class that Douwe had a similar problem and he was as stuck as I was. Together with Henk they figured out through an online search that the installation of MKdocs through homebrew is not working properly. I never realized that the problem was not my novice tries of the program but an installation-issue.

While not getting anywhere with MKdocs, and trying to work with that within terminal,but it was very confusing. I learned that I need a program that helps me a bit more to get my website up and running. First I need a bit of a framework, where from within I can work on the content. Later on work within that on the look and feel of the site and then, if I am more used to the idea of the things that I can work on grow to a more in depth knowledge of the matter.

Like driving a bicycle, first learn how to ride (on a working bike), and after that learn how the gears work and how to fix a flat tire.

HUGO themes

Hugo themes do not work like I had in mind. My idea of a static site builder would be a Lego-like framework where you can easily build a simple house with the blocks that are available. I was firstly looking at the functional parts of the site.

So I want a main part with the content, a side part with a menu that is layered and a simple top-menu for the main parts of the site. What my mental idea of a site generator was that I could pick up these parts from a HUGO database and put them together in a HUGO site builder and, wooshhh I would have a site.

Hmm that mental idea had to be altered quite a bit. So I found out that the practical basis of HUGO is that I write the content and add a theme so I will give the content a good look and feel. Following a lot of tutorials I now understand some basic principles of HUGO:

• the way that directories are the base of the hugo-site
• differences between a list and a single pages
• the front matter part and the main part of the .MD pages
• you can work with tags and categories

But it did not work out the way I wanted:

My requirements were:

• suitable for a blog-like site,
• top-menu,
• layered side menu,
• buttons for forward and back
• a nice minimal look and feel and preferably a homepage with sneak-preview pictures of the different pages
• a way to show several pictures next to each other.

I could not find a theme that would on one side fit my requirements and meanwhile be simple enough so that I could understand the directory-structure.

I started out with a theme called liva

But I could not get anything to work, I wanted to get rid of all the extra things, but could not work that out, so I went back to the HUGO-themes site and tried several other themes(i.a. Book, Dot). But anything I tried other than copying the example-site and changing the content within that would make a terrible mess.

So my learning was:

Start with a very simple theme that only has the main feature that you need.

After this I downloaded the Whisper theme and worked with that. This theme is very simple and does not have all the functions that I will need or would like. At least I can build several pages within this theme and the looks a very simple.

The disadvantage is that I while I figured out how to make a new item in the top directory, with matching pages and all, I lose al the extra bits and pieces like the side menu. For now it is not a problem, since I only have two pages, but I need to figure out a better matching Theme, or understand how to fix my structural problems in order to get the website that fits my requirements.

Visual studio code

Using Visual Studio Code helped me a lot, in practice:

1. You can already preview the pages that you are writing.
2. There is a really handy window for directly using terminal in visual studio code, which is convenient for adjusting the images.
3. There is a lot of steps integrated in the program to upload to the gitlab. which is really convenient.

Making a new post:

In hugo it is possible to make a new post with the frontmatter already there, to do that I use Terminal. Firt go to the right folder and then type hugo new post/weekly/week2/index.md that way Hugo will make a new folder, named 'week2' and in that folder it will make a new post.

Get the images ready for online

I first cleaned up the images (made them smaller) and clean out other files that I don't use (anymore). I used Imagemagick for this in Terminal. In order not to resize all the images in the folder I made an extra folder named '../plaatjes' and I put all the images that need resizing in there. Then in terminal I resize everything to 800 or 1000 pixels wide. this is the same as the maximum width that the page will show them. If the size is okay (say under 100kb) I put the images back in the original folder of this week.

Trying to tweek the theme

I decided that maybe what I need is a lego-builder for HUGO, so I tried to find a more GUI like tool to work in. I tried HokusCMS, online it seemed like a tool that would help me build the different parts of the HUGO-theme that I would like.

I gave it a try, but it was not the intuitive tool that I was looking for. It is much more visual than any other tool I used, but on the other hand i would have to build my site from scratch and I simply don't have the knowledge to do that.

Spiral development, the next step. Find a theme with more documentation and practical starterguide. So I can Next week, I will try the syna theme.

Getting everything online on gitlab.

In order to switch from the standard MKdocs site on gitlab to the HUGO SSG with content that I locally filled.

• Then I made a local copy I also checked if I could get rid of the example web-pages and other static files I think I wasn't using in my theme and the content that came with that.
• After that I did a very 'manual merge': I took the Md files of the MKdocs and fitted them into my HUGO content, adding frontmatter and re-arranging the directory-structure (I found out that images that are used in 'index.md'-files are located in the same directory as a bundle, images that are used in a file named anythingelse.md have to be put in a underlying directory)

In order to switch the content I just deleted all the content on my local clone and pushed the empty directory towards the repository. Everything went fine, the hidden files were still there the .gitlab-ci.yml and the gitignore. I understood from the lessons we had that I had to change the content of the .gitlab-ci.yml site because now it will work with MKDocs instead of HUGO.

From all the other students struggling with this in the past couple of days, I learned that there is not one option to fix this and that are several parameters in the .gitlab-ci.yml that should connect in the right way with the things in the HUGO-Theme.

I gave it several tries with the standard solutions that I found online, but it did not work. Then I tried the versions that Nadieh, Erwin and Loes uploaded, in combination with the information in the Mattermost about that, that did not work either.

With that knowledge, I did a more focussed search on the problem and found a forum where more people where struggling and I learned that the combination of Gitlab and HUGO and Theme is the trigger. So I tried several solutions and eventually found that the version should be HUGO-extended and that my path to the site in my config.toml had to be different.

I got it to work, great.

Uploading new content

To upload new content in Visual studio code I follow these steps:

• go to the 'changes tab' on the right.
• 'stage all changes' by hitting the + sign.
• give the staged changes a name (so if anything goes wrong, you know which things were in what upload)
• Hit the 'V' sign at the top.
• at the bottom of the screen appears a '1' next tu the arrow up, and that means there is one commit ready to push to master
• hit the arrow and visual studio code will push it.

(New) Tools I used

For installing all the software

• Homebrew
• Pip3

Communication and online meeting:

• Webex (online lesson from Ferdi)
• Mattermost
• Jitsi (did not work on BigSur so switched back to working in browser)

Tutorials that needed to be installed

• git-it

For building the site:

• MKdocs (first tries)
• visual studio code (text-editor and Git-client) (with plugins to help certain tasks)
• HokusCMS (HUGO-theme builder)
• Iterm (variation on terminal)

For making the images

• pen and paper (I have it at home)
• Office-scan (I-phone app for scanning and straightening images)
• I-photo (to brighten up the scans)
• Preview (to preview, crop and small alterings like adding arrows)
• Photoshop (to improve images and make animated GIF)
• Imagemagick (to convert .png to jpg's (screenshots) and give them a standard width)
• Illustator (to convert my drawing into a .svg)

[Top]