2. Project management¶
Week assignment - Work through a git tutorial and build my personal FabAcademy website.
First week overview¶
I started to think about the structure of my website while I was flying from Buenos Aires to Barcelona. However, when I cloned the repo and found out that it was build in MkDocs, I realized that either I was going to have to build everything from scratch, or I was going to have to style the page I had.
My decision was styling because I believed it would be faster and thus I would have more time to work on the concept for my project. Well, it didn’t turn out as straightforward as I expected. š
How to find my existing SSH Key¶
The first thing I needed to do was to access GitLab and find the repo of my website.
Then I went to User Settings. To get there I clicked on my avatar image and choose preferences. Then I selected SSH Keys on the panel on the left.
I Followed the instructions on SSH Keys section.
Paste your public SSH key, which is usually contained in the file ‘~/.ssh/id_ed25519.pub’ or ‘~/.ssh/id_rsa.pub’ and begins with ‘ssh-ed25519’ or ‘ssh-rsa’. Do not paste your private SSH key, as that can compromise your identity.
Iāve already had an SSH Key, so I needed to find it before moving forwards.
I went to my Home directory and selected my user. The SSH Key is a hidden file so I pressed command+shift+. to visualize hidden files.
On my .ssh folder I found a file that was named id rsa.pub, pub stands for public. So, I opened the file using the Text Editor and pasted the key into the input field on the SSH section in GitLab.
I then press the button ADD KEY Once I got my SSH key I was able to clone github repository to make the modifications on the site.
To clone the repository I went back to Project Overview section and press the CLONE button. Then copy the URL on the option CLONE with SSH.
I opened the terminal and run
git clone git@gitlab.fabcloud.org:academany/fabacademy/2021/labs/barcelona/students/denise-rey.git
By doing this I was able to get the folder on my local machine.
I used Visual Studio Code to edit the files and Docker to run faster the environment of mkdocks.
To make changes the steps are really easy. First, I open Docker and just click on START and then on OPEN IN VISUAL STUDIO CODE.
Then I open the browser and enter http://localhost:8000/ to visualize my website. I just edit my code, press command+s to save it to be able to visualize my changes before uploading them.
To upload my changes I just click on the 3rd icon on the panel on the left which shows the amount of changes I’ve made. Then I click on the Commit icon (that looks like a check) and I click on the SAVE ALL AND COMMIT button on the modal that pops up. Afterwards, I have to enter a message which should explain in one line why I’m uploading these changes.
Last but not least, I have to click on the arrow to push my commits to origin. I’ll get another modal, press the OK button and it’s done. Then, just check the url to verify that everything is correct.
Good idea: using Docker¶
After checking the instructions on how to install and setup mkdocs locally, I realized that I was going to have to install some tools like python and the mkdocs project. Having worked with Docker before, and since I have it installed already, with some help I managed to create a docker image [Docker file, Docker compose] that already has all the dependencies I needed to start styling the website.
Bad idea: try to customize the theme overriding CSS¶
Since the mkdocs UI component library is very limited, my first attempt was to try to override some of the CSS classes so I could make some components. I wanted to turn standard buttons into something that looked like cards. Eventually, I realized that it was taking too much time and effort so I decided to abandon that strategy and look for better alternatives.
Better idea: use material UI¶
I realized that the default mkdocs theme was using āMaterialā design system so after investigating a bit, I realized that mkdocs has a way to define additional CSS libraries through the external_css property and I was able to easily add the official Material UI library which allowed me to use some more refined components like Cards and the Grid Layout system.
extra_css:
- stylesheets/extra.css
- https://unpkg.com/material-components-web@latest/dist/material-components-web.min.css
In the end, I invested a lot of time but hey, I’ll be iterating it as I progress with the course.
Changes I made to the initial code¶
First, I made some changes on the mkdocs.yml file. I added Material UI as on extra CSS, I changed the social links and icons, I defined some overrides to add the colors I wanted to use, the font and my icon.
# Replace the text below to customize your site
site_name: Den Rey - Fab Academy
site_description: Fab Academy documentation site for Den Rey
site_author: Den Rey
copyright: Copyright 2021 Den Rey - Creative Commons Attribution Non Commercial
site_url: http://fabacademy.org/2021/labs/barcelona/students/denise-rey
extra:
social:
# For other social icons at https://squidfunk.github.io/mkdocs-material/setup/adding-social-links/
- icon: fontawesome/brands/medium
link: https://medium.com/@denalcubo
- icon: fontawesome/brands/twitter
link: https://twitter.com/denalcubo
- icon: fontawesome/brands/linkedin
link: "https://www.linkedin.com/in/deniserey/"
- icon: fontawesome/brands/github
link: "https://github.com/denreyrey"
theme:
name: material
custom_dir: overrides
palette:
# try other colors https://squidfunk.github.io/mkdocs-material/getting-started/#primary-colors
primary: white
accent: purple
font:
# See available fonts at https://fonts.google.com/
text: Be Vietnam
code: Cutive Mono
icon:
logo: material/memory
favicon: images/favicon.svg
features:
- navigation.tabs
plugins:
- search
- git-revision-date-localized:
fallback_to_build_date: true
markdown_extensions:
- extra
- smarty
- admonition
- codehilite:
guess_lang: false
- toc:
permalink: true
extra_css:
- stylesheets/extra.css
- https://unpkg.com/material-components-web@latest/dist/material-components-web.min.css
Then I created a folder named overrides and a file there called home.html to be able to define a different layout for my home page, this file is written in HTML. I also created a file named index.md where I wrote in markdown the components I wanted to use on my homepage.
Additionally, for the customization I added a folder called stylesheets where I created a file name extra.css. I wrote here all the additional changes that I wanted to apply on the website, not only for the homepage:
:root>* {
--md-typeset-a-color: rgb(32, 32, 32);
--md-footer-bg-color: white;
--md-footer-fg-color: rgb(32, 32, 32);
--md-footer-bg-color--dark: white;
--md-footer-fg-color--lighter: rgb(32, 32, 32);
--md-footer-fg-color--light: rgb(32, 32, 32);
--mdc-typography-headline6-font-family: 'Be Vietnam', sans-serif;
--mdc-typography-font-family: 'Be Vietnam', sans-serif;
}
.hide-scroll-bar {
-ms-overflow-style: none;
scrollbar-width: none;
}
.hide-scroll-bar::-webkit-scrollbar {
display: none;
}
.md-typeset .md-button--primary {
border-width: 1px;
border-color: rgb(219, 219, 219);
border-radius: 4px;
}
.cardContent {
padding: 16px;
font-size: 16px;
color: rgb(32, 32, 32);
}
.md-typeset h2 {
font-weight: 500;
}
.mdc-typography--body2 {
font-weight: 300;
font-size: 14px;
}