This week we learned about version control and how to use Git. I have never used Git or created a repository, so I am a beginner. Therefore, to manage my fab academy weekly assignments and final project on Git Lab, I have to learn about Git from scratch. The assignment of this week is to build a personal website using website development tools and upload it to the class archive. In addition, I have to work through a git tutorial after learning about it and finally signing the student agreement.

This week assignment content:

I used the following resource to help me editing my site:

  1. Markdown Cheatsheet.
  2. Markdown Guide.
  3. Basic commands.

Jekyll Resources:

  1. Tutorial.
  2. Themes.
  3. Themes.
  4. Voyager Theme.
  5. Jekyll on Windows.

2.1. Student Agreement

Click here to enter the student agreement page.


2.2. Learn about project management

First of all, since I am a new in using git I have searched and learned about project management main terminology and basics. The following is a short explanation about what is a Repository, a Version Control System (VCS), and a git.

Repository

In fab academy course, all work will be documented in a repository. This method was chosen due to its capability of keeping history of the work saved each time in versions. Repositories can be set individually or by a group of people. Also, it can be set as a privte, which can be viewd and edited only by the author or as a public, which can be viewed by everyone.

Version Control System (VCS)

To write in the repository, a version control system (VCS) should be used. As its name implies, it is a type of systems that can keep versions of the user work every time it committed with a snipping message. The user cannot remove the old versions from the history path. In addition, it allows multiple users to manage, share, and cooperate multiple units of inforamtion. Advantages can be summarized by the following points:

  1. Make an archive of versions.
  2. Maintain versions historical inforamtion, for example auther, date and time.
  3. Enable collaboration, so people can share documents and data easily.
  4. Recover from accidental delections or edits.
  5. Conserve disk space because in each version, it saves only the changes from previous version.

Git

"Git" will be used as a version control system (VCS) since it is a free, efficient, fast, and open source tool. The course documentation will be posted online on "GitLab", which can be edited directly from "GitLab" online website using the text editor, or it can edited locally from a computer using "Git Bash" or "Git GUI".


2.3. Build my personal website

Initially, I have used the template provided on GitLab. Later on, I found many amazing online themes that I can download and push to my repository. The most one I liked and found it very orgnised and easy to navigate was Voyager theme from Jekyll themes. So, basically I went throught the following steps:

2.3.1. Build my personal site using MkDocs

For my first try in building a website, I chose MkDocs since it is the default template available on GitLab repository. As well as MkDocs is easier to learn than other static sites generators such as HTML. My Fab Academy documentation files were written in Markdown formmatting and configured using a YAML file.

What is Markdown ?

Markdown is a plain text formmatting syntax. I use it for web writing and editing to my repository. I chosed Markdown for my first try as it is lightweight markup language, easy to use by the beginners in web dueveloping, and since the available tamplate uses Markdown.

How the MkDocs static site generator works ?

The project template was ready made in GitLab so I didn't need to create a new one and set it up from scratch. However, I have searched about the way I can do it independently and try it myslef. The following steps explain the process.

Step 1: Installation

I installed Python and Python package manager pip on my system and used the following commands in Git Bash to confirm that they have been installed on my system:

python --version
pip --version

Command output is:

Python_Installation

After that, I have installed the MkDocs package and shown its version by the following command:

pip install mkdocs && mkdocs --version

Command output is:

MkDocs_Installation

Step 2: Create a Project

To create and open a new MkDocs project page on my fab academy GitLab repository by typing the following commands:

mkdocs new my-project
cd my-project
ls
ls docs/

Project is created in the following repositroy location.

CreateNewProject

To list all project files type:

ls
ls docs/

Project is created with default configuration of type .yml file and docs directory that should contains all documentaion files. By default, the docs directory contains a doumentation page called index.md.

CreateNewProject

Step 3: Test the Web Page

I used atom software to see how the page will looks like before pushing.

PageTest

Step 4: Create yml file in GitLab

yml_File

Step 5: Local computer set up

To git user global setup:

git config --global user.name "Maryam Ali"
git config --global user.email "mariamaqeel96@gmail.com"

To generate and copy the ssh key for the local computer:

cat ~/.ssh/id_rsa.pub > /dev/clipboard

Then in gitlab online website, open settings > SSH Keys > paste the key > add a title for the key > press add key.

Generate an SSH key

To create a new repository go to gitlab online website, open Projects > Your projects > choose the project you want to clone > press Clone > cope Clone with SSH

Clone

Write “git clone” and paste the copied clone in the Git Bash command window

git clone git@gitlab.fabcloud.org:academany/fabacademy/2020/labs/bahrain/students/maryam-ali.git

After cloning the project, repository folder will be created with the name and the location I set on my local computer. Now I am able to edit my documents locally from my computer and push them to my GitLab online repsitory. The following command will should be used to push changes to GitLab:

git add .
git pull
git commit -m 'update'
git push

2.3.2. Build my personal site using Jekyll themes

After learning about MkDocs, I looked for other themes on the internet and I liked to use Jekyll themes. Steps followed are explained below:

Step 1: Installing Jekyll

To install the Jekyll on my laptop (Windows), I followed this tutorial. Based on the tutorial, I should first isntall Jekyll and Bundler via:

gem install jekyll bundler

install_jekyll_bundler

To check if Jekyll installed properly:

jekyll -v

check_install_jekyll

To set up the server and build my site:

Jekyll serve && Jekyll build

serve_and_build

I can copy and paste the server address shown in the command line to browse the generated page (i.e. http://127.0.0.1:4000/).

server_address

Step 2: Configiration settings

Add this part to the beginning of each weekly assignment.

configiration_settings

Change the content of the .gitlab-ci file to:

configiration_settings_2

Change urls in _config.yml file to (baseurl: “/2020/labs/bahrain/students/maryam-ali”) and (url: “http://fabacademy.org”).

set_config

Step 3: Default files created

myWebsite: main high level folder.

_posts: folder that will be used most of the time to add my work.

_site: final output of the website (static files), it holds the final version of your website. It will be updated for you, don’t modify anything inside it.

_config.yml: the setting for your Jekll website.

Gemfile: file used to store and specify all of the dependencies of your website. (e.g. the website theme).

Index.md: home page of your website.

project_tree


2.4. Create a git tutorial

To create file directory:
mkdir file name
To open file directory:
cd file name

You can also open file directory by going to the file in your local computer and right click “Git Bash Here”.

Open file directory

To generate a list of files:
ls
To enter text editor:
vi
To produce a list of what you write already:
History
To get all files included the hidden ones:
ls –lah
To create a file without open it:
touch filename.md
To create file directory:
mkdir maryam
To create file inside a file:
mkdir maryam/imag/week1

2.5. Problem faced

Somtimes when I create a new page or add a new image, the jekyll cache is not produced automatically, so I should push the _site file manullly. To do that, I used the following command line:

git add -f _site

⤧  Next post 3. Computer Aided design ⤧  Previous post 1. Principles and Practices