1 of 25

2 of 25

How to Document

Git, Markdown, GitLab, mkDocs

JULIAN GALLIMORE - SETP 2020

3 of 25

Agenda for today

Online infrastructure

mkDocs

Markdown

How to customise mkDocs

About Git + Gitlab

4 of 25

Fabricademy

Online Infrastructure

5 of 25

Fabricademy Online Infrastructure

Fablabs.io

  • Online platform that maps the FabLab network world-wide
  • Provides the user account logins for our tools GitLab & Nueval

6 of 25

DEMO

Now let go reset your fablabs.io password (if haven’t done this yet)

7 of 25

Fabricademy Online Infrastructure

GitLab

  • Open source software for hosting your Git projects in the cloud
  • Similar to GitHub, Bitbucket
  • We host our own version of Gitlab at gitlab.fabcloud.org
  • This is where we host all the academy websites and where you can can edit your documentation website

8 of 25

DEMO

Let’s try to login to GitLab using your fablabs.io account

9 of 25

Fabricademy Online Infrastructure

Nueval

  • A platform created to track the students' weekly progress and evaluation
  • The evaluation process will start in April
  • Divided in two phases:
    • one evaluation by the local instructor
    • then by the global instructors
  • http://fabricademy.fabcloud.io/handbook/assessment/criteria/

10 of 25

Your documentation website

11 of 25

Your documentation website

  • The website is hosted on GitLab
  • Using a language called Markdown
  • Built using a tool called mkDocs
    • Compiles your markdown to HTML
    • Can do some basic customising of the style
  • All pages have dummy placeholder data to help you get started why documenting

12 of 25

language: Markdown

  • For formatting elements in plain-text format
  • Allows to structure your content without writing HTML

13 of 25

What can I customise on my website

14 of 25

Where do we start?

  • Edit our site files by using GitLab’s browser editor (called Web IDE)
  • We can click the “edit” button for easy access to start editing in GitLab

15 of 25

mkDocs folder structure

  • Some of the files in your repository

​

​

​

​

​

​

mkdocs.yml

Mkdocs configuration file. You need to edit this file to personalize your website.

docs/

This folder contains all the website content. Only files inside this folder are published to your website!

docs/index.md

This is the homepage. Edit this file with your profile and information

docs/images

This folder is meant to contain all images in your website. Make sure you check the file sizes for your images. There is a 10MB limit per commit, but suggest to keep your images around 100 kb or so.

.gitlab-ci.yml

GitLab CI pipeline instructions for building and publishing your project. Don’t touch them unless you know what you are doing.

16 of 25

mkDocs configuration

  • All settings for mkdocs are found in the mkdocs.yml file

17 of 25

mkDocs Theme

  • Currently using the mkdocs Material theme
  • Allows to customise the colours, fonts & icons

​

​

​

​

​

  • Possible colours:

18 of 25

mkDocs Fonts

  • The Material theme allows you to change the fonts
  • Use Google Fonts to find a font
  • Edit your mkdocs.yml file to set the desired font

19 of 25

DEMO

Customise mkDocs

20 of 25

Markdown

​

  • Read through our Documentation Handbook

![](../images/sample-photo.jpg)

21 of 25

DEMO

Let’s try out what Markdown can do in mkDocs

22 of 25

Create an issue in your GitLab project and we will help you

“I have a problem”

23 of 25

Extra features of GitLab

  • Issue Tracker (for asking for help on issues)
  • CI pipelines (for automatically building your project)
  • Pages for hosting static websites
  • Web IDE (text editor in the browser)

24 of 25

So what do I do with Git

  • Git is a tool used for tracking to your project files
  • Saving your changes is called a Commit
  • Everything is stored in a Repository
  • You can view all the commits in a repository to see who/what/when changes were made
    • If anything breaks, look back at your commits and undo what you did
  • You can also have a Git repository on your computer
    • After any changes to files you can push your commits to the cloud (GitLab)
    • The repository in GitLab is called the remote origin (this of it as the master version)

25 of 25

How do I publish my website

  • Every time you make a commit or push to GitLab
  • CI pipelines will build your website every time you push a commit
  • You need to pay attention, if there is an error anywhere your website will not have updated.