Summary
Well what a first week! So much information to absorb, research and learn about. Part of the time was orientating around the FAB-universe and how the course would run and where to find everything you might need. The other part was introducing new (at least for me) ways of working, environments in which to work and what seemed like an unending list of links and tools/software to research and learn. The first night all I dreamt of was links. The main problem with that was I had very little idea of how everything fitted together into a workflow. As well as which of the unknown tools/software to use to do it.
Learning Outcomes
Theory and use of things i learnt from this assignment:
- Command line environment
- SSH
- Git environment and commands
- Static Site Generators
- Markdown and Yaml languages
- General orientation of the Fab universe
- Project management
- Version control
- Spiral Development
- Rubber Duck debugging
- Fab Academy principles & practices
Lessons to take away:
K.I.S.S - Keep It Simple Stupid. A design principle, which should apply to the idea of the final project as you won’t have much time to finish it.
Rabbit holes. When trying to solve a problem, give yourself a time limit. It’s very easy to fall into rabbit holes on the internet looking for a solution, only to find it brings with it more problems to solve, than trying a different approach.
Read the output of the console slowly. IF there is a problem it will helpfully describe what is wrong and potentially suggest a solution. Best done when it’s not late and close to the deadline.
What I did
I tried to learn as much as I could about everything at the same time. Through video tutorials and usage guides for all the different software and environments, I narrowed down which tools I would use from the large list.
At that point I practiced installing and using the tools chosen, to check which worked for me on my machines. As i hadn’t managed to unravel the workflow and connections between the tools these were done in isolation from each other. Setting up a Git environment, using the command line, installing a Static Site Generator, exploring Gitlab etc.
With very little idea of what i was doing, or how to do it, i think i managed tom ake nearly every mistake possible (far too many to document). But there was a little light at the end of the tunnel.
As it turns out, Fablab have already created their own Gitlab environment with everything setup for my own repository (and website) there, so some of the work has been done already. Practicing gave me a good grounding of what everything was about and how it worked. And it allowed me to make most of the mistakes, and learn from them without messing up Gitlab.
What I should’ve done
INSTALL on local machine
Git comes pre-installed on Mac OS, so the process didn’t need to begin there. For ease of use, future updating / version tracking of code and commands of programmes related to git, programme packager is needed.
Homebrew (program packager)
I installed Homebrew, to do all this:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
SSG (HUGO)
Having experience developing sites in Wordpress (a dynamic site system), this came a a new concept to me. A static Site Generator builds the website before hand ad the time of development and not at the moment a user requests it from a site. I choose Hugo over MKdocs as the themes in which to customise it looked fancier.
This installs Hugo:
brew install hugo
Creating a new site you use this:
hugo new site [project name]
To initialise the git tracking of the site:
git init
INSTALL THEME
To install a particular theme to wrap the Hugo frame work into, you’ll be sent to a git repo of the theme. Here you can download the latest set of files. Once downloaded, unzip into the ‘themes’ folder of the Hugo install and amend the config file in the Hugo install to include the name of your new theme. This will now point Hugo to use the newly installed theme.
(in Yaml language)
theme: dot
Check website
Checking if the local website is working by the hugo specific command:
hugo serve
It starts the local server and will give you a link to open in the browser to see it rendered as it would on the remote server.
Make a connection with gitlab using SSH
Secure SHell is a secure network protocol, using a pair of ‘keys’ to establish secure connections between computers.
For this to act as a seemless “password” exchange between me and the repo each time i work with it i needed to make a private/public key pair.
Checking to see if i had one i could re-use i looked in my .ssh folder. Nothing, Nada, Niets.
So creating one (with rsa encription) was easy with this command:
SSH keyssh-keygen -t rsa -C "$your_email"
To read the public key:
cat ~/.ssh/"$your_email".pub
This public key needs to be registered with gitlab in your User settings > SSH Keys. If it works, this command will give you a nice welcome message:
ssh -T git@gitlab.fabcloud.org
IF this doesn’t work at any point afterwards, the SSH key might need to be added to the config file in ‘.ssh’ folder if it has one.
Clone gitlab
Whilst still in the Gitlab web interface (Project Overview), a handy blue “Clone” button allows you to copy your personalised link to the gitlab repo. Together with the git clone command, all the files are downloaded (hidden files as well) into a folder. That simple!
Swap the local Hugo site for the cloned Repo
Deleting the files and replacing them with the Hugo installed site sounds daunting, but as long as you don’t delete the hidden files from the original repo clone the connection will stay and you should be fine.
Visual Studio Code
I chose this piece of software as it had been recommended by others as a code editor, with the added features of tracking files and included command line abilities to manage the repo process. The newly cloned folder was “Added folder to workspace” of VSC. A little git status in the command line showed me VSC could see everything is connected through it.
As it says in the title, it is a more visual way of working with files and includes buttons to activate command such as, git add, git commit, git push etc. This seemed less scary that the dark abstract world that is the command line.
Syncing Machines
Once a site is working on my desktop computer, with all connectivity with the gitlab repo tested and functioning, then i can repeat the cloning process of the repo onto my laptop. (All software had been installed earlier).
I decided to make and use a second SSH key that was specific to my laptop for smooth access to Gitlab. A simple “Welcome” reply from Gitlab on the command line confirmed connectivity was there and i cloned the repo.
A git status command confirmed i was up to date with the gitlab repo and the universe was now in balance!
Make Content
This is done using Markdown language, a sort of simple “shortcut” language that is then replaced by raw html when the site is built. Like a simple text editor, simple formatting of content is possible - as well as adding raw html when you need more (this hasn’t worked so far - a safety feature is enabled somewhere i think).
Any content made/changed need to be added to be “staged”, flagged that it has changed and is added to the “commit” queue. git add [filename], or git add . for the whole directory you’re in. Once all and any additional changes have been made, the “commit” queue can be finalised and ready for pushing to the remote repo, git commit -m "add description of changes", git push.
As part of making the content, emphasis was put onto the best practice of compressing image and video assets before uploading to the repo. This will keep the data size of the as small as possible. As a multimedia designer i’ve worked with Photoshop before, so that is the program i made the images with and compressed them for web use, with the File > Export > Save for web option. Compressing them in Jpeg format to 60% quality, 800px x 600px pixel resolution when no need for transparency, and PNG format when there was need. All having a data size of approximately 100kb.
Customise Templates
At this point, time is against me and i won’t be able to research the way the Hugo framework works and how i can customise my layout. I managed to change a couple of parameters of the theme in the config file, but any more than that will need an understanding of the way templates are made up and their use of their own code.
update
Originally I had thought to re-create my own website (StinkFish.nl) animated header for this Fablab site. But working out how to transfer it into the Hugo theme structure was taking up more time than i could spare.
I’ve been customising the theme as I go through the weeks, some have been simple changes like turning everything orange ;), where as adding ‘partial’s to the mail HTML files will need some extra research to use the Hugo ‘functions’ language to call for data from the other the files. It would be nice to include features that come as standard in other peoples (too late to change themes now!). See below for the issues i ran into.
Mistakes & Issues
I watched a lot of video tutorials and read lots of “quickstart”/Installation instructions (probably too much!). At some point I made an Access Token on my Gitlab project which I thought (Visual Studio Code Gitlab extension asked for one) was needed to set up the connection with my local host site. This isn’t needed and has the effect of confusing the Systems Admin and unbalancing the force in the universe.
Trying to install Jekyll as a SSG was a problem. My wish was to be able to work on my documentation on 2 machines. A desktop with 2 screens while I work at home, and a laptop when I’m at the lab.
The root of the problem was that the laptop was a new Apple laptop containing the (new at time of writing) M1 Chip processor. This new processor architecture had difficulty using the particular code and dependencies used in the installation and working of Jekyll.
After many hours or research and trying to find a solution that worked. I gave up and installed Hugo instead - I had no trouble installing it on the laptop so considered it safe to use on both.
Adding Raw HTML to the Hugo theme
UPDATE
In further weeks I needed to include videos into my pages. There wasn’t a ‘shortcut’ for this in Markdown language, so i resorted to adding it with HTML. Upon rendering the page in a web browser, no video could be seen in the page. I checked my HTML in case there was something wrong with the code; there wasn’t.
Next i looked at the HTML of the rendered page in the web browser. At the point where i expected the video code to be there was a commented line:
<!-- raw HTML omitted -->
A strange comment i’d never seen before when coding websites. But acknowledgement of my attempt at inserting raw HTML into the page directly.
I searched on google for any reason why Hugo (or the theme) wouldn’t allow raw HTML to be inserted - contrary to the insistence that Markdown can accept raw HTML (according to ‘Neil’, which even God doesn’t question him).
Others with other themes in Hugo didn’t have this problem (and others did!). So i deduced that my theme was missing something essential to make it accept raw HTML. Searching through the HUGO documentation and related ‘How to customise HUGO’ articles on the internet, I came across someone who had made their own theme ‘shortcut’ for this exact problem:
<!-- raw html -->
{{.Inner}}
This code tells Hugo to simply render the inner content passed to your shortcode directly into the HTML of your site.
To get Hugo to register this file (and therefore the code) it needs to be added to a specific Hugo core folder, just like all other customisation files you might make. Placing these files in the correct Hugo core folder (or your customised file with the same name) will override the theme files or add extra functionality.
For the shortcodes, seperate files (for easy organisational purposes) are saved in the folder:
[layouts] > [shortcodes]
Adding code (shortcode) around your content such as below triggers the functioning of the code.
Customising the look of the theme with CSS (and images).
custom_css : "css/custom.css" needs to be added to the config.yaml file to define where the theme should look for customisations.
Adding customisation is as simple as writing the CSS code in a file and save it as ‘custom.css’. But of course you need to add it to a specific place in the Hugo core folders. Hugo will automatically look for customised CSS in the folder:
[static] > [css]
any images you want to refer to in the CSS (e.g. the favicon) you can add in the folder:
[static] > [images]
e.g:
/**************************************** custom css
// fonts*/
h1, h2, h3, h4, h5, h6, .navbar-nav, .sidebar, nav.pagination {
font-family: "Amatic SC", cursive;
}
body, nav#TableOfContents ul li {
font-family: "open sans";
}
h3, h4, h5, h6, nav#TableOfContents ul li a{
text-transform:capitalize;
}
Modifying the Theme HTML files.
This is a little more tricky. For the main core html theme files such as index.html, they might be made up of ‘partial’ chunks of code based in other files. That was the case in this theme. For me to override the html files in the theme i copied the theme files into:
[layouts] > [partials]
And adjusted the html in these files to my liking. for example adding the student agreement to the ‘footer’ part of each page. (See results below).
CONCLUSION
Thrown in at the deep end, I’ve had a very quick grounding in lots of different working environments, ways of working, software packages and computer languages.
A website is up and running! :) I’ll continue to update and tweak things as the course goes on. And of course add more content each week!