1. Project Management¶

To document my work during my time at Fab Lab, I will be using this website.
To simplify this process, a template is provided to us written in Markdown language. Markdown is useful here because it is an easy to read language that will allow us to focus on the documentation process without having to deal with the extra complexity of writing in html.

The template code was shared using Fab Lab’s GitLab instance. The files should look like this:

To better understand what I was doing I did some Googling and apparently GitLab is a web-based Git repository. While Git is the version control system used to manage source code and project history to ensure no progress is lost due to some mistake. This means we can experiment all we want because we have a sort of safety net 😄.

The docs folder contains the site documents that we will be interacting with, while the other files are there for support and to convert the site from Markdown to html language. The conversion to html is done by using MkDocs, which is a site generator that is aimed to provide a simple experience for documentation.

Deploying The Website¶

After receiving access to the template code, the website can be accessed by following these steps:

Navigate to Build then Pipelines from the side panel:
It should look like this: Click on Run Pipeline in the top right, then click on Run pipeline again: The process will first be pending before it runs. After it finishes running the page should look like this: Finally, by going to Deploy then Pages, the site link will be available:

This link will take you to the uncustomized template’s homepage.

Changing Website URL¶

The site link that was generated is very long and filled with random characters, it is possible to generate another link that is shorter and easier to read, by unticking the Use unique domain checkbox from the same page.
Before:
https://ali-aljeshi-fablabbh-asterisk-2024-5f55b38d3371cb489f6522169a3d.fabcloud.io/

After:
https://fablabbh.fabcloud.io/asterisk/2024/ali.aljeshi

This will render the site inaccessible for a short while, so be careful.

Cloning The Website¶

It is possible to edit the site by editing the markdown (.md) files online directly from GitLab.

However, this method is inconvenient and limited, hence, using a dedicated code editor is preferred. We will be using Microsoft’s Visual Studio Code because it is lightweight, simple, and free.

When downloading software I kept all settings on their default value because I don’t really know what they mean :|.

To use Visual Studio to edit our website’s code we need to have a local copy. To clone the online files available on GitLab to our computer we used Git Bash.

Git Bash is a command-line terminal environment that allows for the use of Git commands in Windows.

After installing Git Bash a new option is available in the right click menu in Windows:
This option opens Git Bash and refers it to the current directory, so, we must first navigate to the location we want the site folders to be saved and then right click.
This console that opens looks like this:
Notice the directory is a folder called Fab Lab on the desktop, which is the desired location.
Now it is possible to use commands to clone the files.
The command used is: git clone *Website_Link*

To get the website link we go to GitLab and click on the code drop down menu on the project main screen and copy the clone with HTTPS URL:

The command should look like this:

GitLab should ask you to Sign in. Just use the password option and enter the username and password you used to create your GitLab account.

It should download the files, which will then be available on your computer.

Additional commands are done to basically give author credits to you when editing the code:

The cd command is used to change directory to be inside the main project folder of the website.

the git config commands are used to set configuration variables, they are used with --global to ensure that the configuration is applied to all Git repositories that we work on instead of only this one.

the user.name command and user.email are used to associate your name and email as the person who is creating or editing the files.

Preparing to Edit The Website code¶

Using Visual Studio Code the project folder is opened.
This is done by pressing File the Open Folder and navigating to the project folder and pressing select folder.
A popup will appear asking if you trust the author. Click Yes.
The files from GitLab should appear in Visual Studio, and they can be edited.

When editing a file a notification will appear on the left panel on the explorer tab. This indicates that there are unsaved files.

This disappears when saving using Ctrl+S or by going to File then Save All.
What appears next is a notification on the Source Control tab. This indicates that there are changes done locally that have not been uploaded to the version on the cloud.

To resolve this we must commit and sync changes with the master file on the cloud. A comment must be added to each commit.

Syncing changes to the cloud doesn’t only refer to changes to the code, it also refers to syncing other project files that were altered, deleted, or added.
For example, to add local images to be used in the website, the image files need to be present in the project folder. To do this we can upload them directly from GitLab, or simply copy them to the local clone of the project we have on our computer, doing this requires a commit and the changes be synced using the code editor used.

Extensions¶

While using Visual Studio Code we used 2 extension to help us with the documentation process.
Extension were obtained from the extension tab on the left.

Markdown preview
This is an extension used to show a preview of how the webpage will look like after it has been converted to html. It is not 100% accurate, but it is useful to see how the page should look.

The preview can be seen by clicking the split screen preview button.
Or can be accessed by pressing the shortcut Ctrl+Shift+V

Code Spell Checker
This extension is used to identify misspelt english words in the site code.

it does this by underlining the misspelled words in blue and giving some suggested words in the quick fix tab that appears when you hover over the word.

Editing The Code¶

Since the website is written in Markdown, editing is relatively easy, even if it is limited in customization. To implement options that are not available in Markdown, html code can be used, this code will simply be ignored when the site code is converted from Markdown and should work as normal html code.
For example to move to the next line you can just add two spaces, or alternatively use the html solution of adding <br>
To mark headings just add hashtags. The number of hashtags used indicates the level of heading
# Heading 1
## Heading 2
### Heading 3
For example:
# 1. Project Management
## Editing The Code
### Cheat Sheet
This is the same ordering used in this page

To add images to following code is used:
![Alt_Text](IMAGE_Link "Image_Title")

Alt Text is a brief text description of the image that is displayed when the image is not loaded, or is read by assistive technology for accessibility purposes.

Image title is some text that appears when hovering over the image with the cursor.

Both of these fields are optional and can be left empty.

The image link can be a URL from a website or a relative link referring to an image saved to the project folder. When using a relative link to insert an image be careful since it is case sensitive and also needs the correct file type extension.
For example, to insert an image in the current page week01.md the code is:
![](../images/week01/Explorer_Notification.png)
The two dots at the start represent the file directory level relative to the target file, i.e. how many folders the web page file needs to exit before entering the appropriate location of the image. This can be seen in the file structure of the project folder:

To illustrate, the index.md web page is one folder above the week01.md page, hence, linking the same image in that web page would only need one dot.

Cheat Sheet¶

This syntax can referred to using a cheat sheet. The one I used was this courtesy of DataCamp

Using html To Get More Formatting¶

Inserting images in Markdown does not allow for any formatting options such as aligning. To do this, some html code including the align command can be used:
<p align="center"> <img src="Image_Link" /> </p>
However, because image linking is different in html compared to Markdown, an additional directory change is needed. For example:
In Markdown: ![](../images/week01/Explorer_Notification.png)
In html: <img src="../../images/week01/Explorer_Notification.png" />
This different image location linking can be seen when inspecting an image from a browser by right clicking:

The image code after it has been converted to html:

Notice the additional ../ at the start of the image source.

Image size can also be altered using html code. The picture on the web site home page is inserted using the following html code:

<p align="center">
<img src="images/King_of_Kleenex.jpg" title="The King of Kleenex greets you" 
     width="342" 
     height="400" />
</P>

The image is centered and has a specified height and width value, additionally, a title is added which is shown when hovering over the image.
Also, notice the different image link present, this is because the webpage is located inside the docs folder and not within any subfolders, hence, it does not need to exit any directory.

You can also use html tags to create collapsible blocks:

Click Me!

Hi ☺️

The code to do this is:

<details>
  <summary>Click Me!</summary>
Hi ☺️
</details>

Customizing Website Using .yml File¶

The template used is called Material and it is made using MkDocs, which is a static site generator. To customize the site’s appearance a file called mkdocs.yml is used.
At the time of writing this, mine looks like this:

The first 4 lines had a space to enter your name to make the site yours.

To edit the social media links present on the bottom of the page, the social section under extra is used.
By default there are 4 social links, however, they can be altered as needed.
To do so you must pick an icon from the fontawesome brands icon library found here, and change the referred icon address.
For example, to add my Goodreads profile I will find the appropriate icon from fontawesome:
The icon is called goodreads-g, using this icon name and the relevant link, a new social link can be added.

This appears at the bottom of the page along with any other socials.

This icon is bundled with the fontawesome brand icons, to use icons from another location or library the referring will be different.
For example, to use the school-flag icon from fontawesome with solid theme: fontawesome/solid/school-flag

To see how to refer an image use the Icons, Emojis page from the Materials for MkDocs web site. You can search an icon and see if it is available by default in the template, from there you can see the icon name. Just replace the - with / in the location (keep - if it is in the name of the icon itself, like the example shown above).

Site Colors¶

The template also allows for changing the site colors, you can see the available colors and the resulting appearance on the Material for MkDocs page.
I decided to make my page dark mode by adding a line to change the color scheme to slate. Additionally, I opted to use Green as the primary color and Yellow for the accent color for my site.

I believe that the resulting appearance looks good. Hopefully you agree.

Site Font¶

The template has existing integration with google font, so, changing fonts is as easy as finding a font you like at google fonts and typing its name. There are two different fonts used in the site, one for all the text, and the other for the code. The default fonts are Ubuntu and Ubuntu Mono respectively.
I chose Roboto for the text and Courier Prime for the code.

Site Icon¶

There are two files to represent site icon, one is called logo which is the one that appears on the site’s top bar:

And the other one is favicon, which appears on the site’s tab on your web browser:

These icons can be changed by downloading an icon as a .svg file or .png with a transparent background. Additionally, Logo can be referred from the icon libraries bundled with the template similar to the social icons.
To use icons that were downloaded the linking looks like this:

Note that by default the logo is under icon, this is because it is taken from the bundled icon libraries, so to use local icons the logo must be removed from under icon.

The current site favicon was taken from this site.

Embedding Files¶

In the following weeks we will be dealing with more design files that we would like to share on our website. There are methods to embed these files for other to view.

For Download¶

The method of sharing files for other to download is easy, it is just like linking a website link:
[Click Me](Link)
For example, you can click here to download a keychain I made in Cuttle in week 2.
The code looks like this:
[here](../files/week02/Testing - Keychain.svg)
Notice that the file linking is using the same method as image linking.

Embed Videos¶

To make videos play directly from your website, without having to switch tabs or copy links, you can simply use the embed option when sharing from the desired website.
For example, the following video was very helpful when researching for my final project.

I did this by clicking share on the youtube video then selecting the embed option:

Afterwards, some html code appears, just copy this code and paste it in the website and it should work:

This method works for any video hosted on a website with an embed option when sharing.
To embed local files that have been uploaded to your gitlab, I used this code:

<figure class="video_container">
  <iframe src="Video_Link" frameborder="0" allowfullscreen="true" height="388" width="690"> 
</iframe>
</figure

The video linking is the same method as the image link. I found that these height and width values are optimal for the current website template.
Additionally, when uploading videos to your gitlab don’t forget to compress them, I used Clideo to compress my videos, it reduces file size drastically while maintaining a viewable quality.

Embed 3D Models¶

It is also possible to embed 3D for viewing directly in the browser. Like this simple car model:

Car by AliAljeshi on Sketchfab

To do so we use a website called Sketchfab. To use it you need to create an account. For simple purposes like this, a free account is enough.
After uploading a model, you must make sure that it is public and available for download. It is recommended that the model is in .stl file format:

Then you can publish it on sketchfab. From there you can click on the model and click on embed. Similarly to embedding videos, simply copy the html code that appears and paste it into your website. Additionally, the optimal size of the frame I found for the video is the same for models being

height="388" width="690"

you can add this to anything you embed by including this in the <iframe> command.

The following code to take you to the page top was inspired by Fabián Rivera’s website.
It looks like this:

<a href="#top" class="w3-button w3-black w3-hover-dark-gray w3-round-xlarge">To Top</a>

To Top

Last update: September 18, 2024