1. State of the art, project management and documentation¶

Research & Ideation¶

This was the first time i heard about Markdown, but i sincerely thought it was very user friendly, as i'm no expert in web development. There is a lot of Documentation around this and it helped me customize the website as much as i liked it. First of all, What is Markdown? According to the internet: Markdown is a lightweight markup language that uses simple plain-text formatting to create web content, documents, and README files.

The first thing i did to customize the website was open the online IDE through the gitlab.fabcloud and try to figure out what does anything mean. Fortunately the documentation was very straightforward and I was able to find how to tweak the style of the template. For what i understand, the file mkdocs.yml in the repository is the one that defines the whole website, kind of where the template is defined and loaded through the web browser. I wanted to have a dark theme so, in the mkdocs.yml file i added the scheme: slate on the palette definition, which changes the overall theme to dark. I also changed the colours on the same palette definition to lime for primary theme color and purple for accents, as you may see. But there was something I didn't like about the theme, I wanted to change the font and colour of the headers/titles, but how?

theme:
  # The name of the theme, needs to match your requirements.txt file
  name: material
  # Material theme options:
  palette:
    # try other colors from https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
    scheme: slate
    primary: lime
    accent: purple

After reading the documentation, i found a file called extra.css which is also a text file in which one can add different styles, and is linked to the mkdocs.yml file. How to link this css file to the main one? It is already written in the code but "hidden" with #, which for what i understand, make the browser ignore these lines of code and carry on. What i did was remove the # on the extra_css part, and you could also use javascript through the same process, but i'm not feeling that adventurous just yet.

# Read more here https://squidfunk.github.io/mkdocs-material/customization/#additional-css 
# extra_css:
# - stylesheets/extra.css

# extra_javascript:
#   - 'javascript/extra.js'

The next part was to open the stylesheets/extra.css file and find out how to define the font and colours for the titles/headers. What i found out in the documentation is that first, one has to import the font file either through a link from google.fonts, or download it, save it in the repository and load it from there. I chose the first option, and the people at google.fonts are kind enough to provide the whole process on the Embed section of the chosen font.

Google.fonts embed section on the Bebas Neue font

I copied and pasted only the @import url('https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap'); so the browser knows to, first of all, import the font. And then we have to define that this font is used only on titles, which is written like this:

/** Add your extra/custom CSS classes below */
/* Fuente distinta solo para títulos */
@import url('https://fonts.googleapis.com/css2?family=Bebas+Neue&display=swap');
h1, h2, h3, h4, h5, h6 {
    font-family: "Bebas Neue", system-ui, sans-serif;
    font-optical-sizing: auto;
    font-weight: 400;  
    font-style: normal;
    color: #aeff22;
}

As i mentioned back there, first we define that the browser imports the font from the URL, then through the tags h1, h2, h3, etc. we are defining that this font and colour is used only on titles/headers.

Change the colour using Hex code

I used the online tool HTML Color Picker to help me find the closest lime green to the theme template.

After commiting and pushing the changes, and waiting a little bit, we went from having this:

To having this custom fonts and colours:

The next important thing was adding the images and linking them correctly. The uploading is very easy and straightforward. We have to go first to the Gitlab.Fabcloud interface, move around through the directory and find the /docs/images/home folder. Over there is a matter of finding the + to upload a file.

And the most important part is to link them correctly so the browser knows where to find the photo in the repository and properly locate it in the document. Having understood this, the rest was easy peasy lemon squeezy as the template has all the information for having different formats around the documents, like tips, photo alignements, tables, charts and titles.

I'm really liking the Online IDE as it is very easy to commit and push the changes, review the versions and in general having a streamlined workflow. How do one commits this changes? as simple as going to the Source Control menu and commiting and pushing to 'Main'

Commiting and Pushing changes on the main branch

It is important to make sure every commit/push is as light as possible, because there might be a limit on data one can push, and returning to the different versions may be complicated.