Skip to content

0. Documentation

Let's start by documenting the documentation process! I split the first week's content in two: this page addresses some of the technological aspects of this documentation website. The second page presents some areas and projects I am interested in.

Getting started

I have a lot of practice with Git, but I actually didn't have experience with automated pipelines and mkdocs, so I was very excited to play around with the setup. I started with simple cosmetic tweaks and spent way too much time on Google Fonts picking the perfect font (I settled on Poppins – mostly because of the name).

mkdocs.yml

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
theme:
  # The name of the theme, needs to match your requirements.txt file
  name: material
  # Material theme options:
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: blue grey
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: blue grey
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  font:
    # See available fonts from https://fonts.google.com/
    text: Poppins
    code: Roboto Mono
  icon:
    # Read about icons at https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/
    logo: material/robot-confused-outline
    favicon: material/robot-confused-outline
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - navigation.top

Then I experimented a little with different themes: Bootstrap, Cinder... It was a good way to understand how to install extensions and get a grasp of how the pipeline works, but I quickly realized that the default theme, Material, was my favorite, so I reverted to it.

Having fun with extensions

While looking at different themes, I stumbled upon PyMdown Extensions. This is a collection of extensions for Markdown that add some cool features, some very useful and some just plain fun. In order to use them, you simply need to edit the mkdocs.yml file at the root of the GitLab directory and add the extension to the markdown_extensions list, like so:

mkdocs.yml

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
# See more extensions at https://squidfunk.github.io/mkdocs-material/reference/
markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true
  # https://squidfunk.github.io/mkdocs-material/reference/admonitions/
  - pymdownx.details
  # https://squidfunk.github.io/mkdocs-material/reference/content-tabs/
  - pymdownx.tabbed:
      alternate_style: true 
  - pymdownx.critic
  - pymdownx.magiclink
  - pymdownx.tasklist
  - pymdownx.superfences
  - tables
  - footnotes
  - attr_list
  - md_in_html

Somes extensions were already added to the default website:

pymdownx.details

Details builds on Admonitions, which creates call-outs (titled boxes used to highlight some content) using the !!! marker. Details makes these boxes collapsible with the ??? marker.

You can add a class to determine the style. These are the classes that are already defined by the Admonition extension:

note
abstract
info
tip
success
question
warning
failure
danger
bug
example
quote

I decided to use the example class for code snippets.

pymdownx.tabbed

Tabbed lets you create tabs so that you can switch back and forth between different chunks of content.

👈

👉

pymdownx.superfences

Superfences allow all those admonitions and details and tabs to be nested, to infinity and beyond! To nest a block in another, you simply need to indent it with a tab (or four spaces).

One level down...
Two levels down...
Three levels down...

And many more to go!

🐇🕳️

Here are some additional extensions I enjoyed:

pymdownx.critic

CriticMarkup is an easy way to display revisions and comments on text, similar to what you would get in Word when you have revisions enabled.

Text can be deleted and replacement text added. This can also be combined into onea single operation. Highlighting is also possible and comments can be added inline.

pymdownx.magiclink

MagicLink is very straightforward, basically auto-linking HTTP, FTP and email links that are written in plain text (no need to use markdowns). The resulting links look like this: http://fabricademy.fabcloud.io/handbook/

pymdownx.tasklist

Tasklist lets you create checkboxes that can be shown as checked or unchecked:

  • Create documentation
    • Write bio
    • Research state of the art
      • Watch videos
      • Read websites
    • Upload images
  • Take a nap

There's even an option to make them clickable!

I knew I wanted a way to include multiple pictures that would result in easy-to-read and aesthetically pleasing pages. Tables didn't do the trick for me, and surprisingly I couldn't find a readily-available mkdocs extension to create carousels or lightboxes. I decided against my best judgement to implement one myself.

First, I tried using Lightgallery in Markdown. This was much more of a pain than expected, both because the package wasn't maintained and because I was still finding my way around mkdocs. In the process I learned two very useful tricks: - adding a package in requirements.txt straight from GitHub (using this line and replacing git with https as indicated here) - overriding template blocks to add some custom javascript code to the header or footer of a page

I also had to hunt down an older version of lightgallery.js and do a lot of debugging. When I finally managed to make it work however I realized that the lightgallery-markdown extension only supported one image per lightbox (as documented here)! I could make it work by writing HTML code instead of using markdowns, but the result still wasn't close to what I wanted, so I decided to start from scratch.

Then I looked into MkDocs GLightbox, which seemed much easier to use with the Material theme. Looking at the demo though I realized that pictures were all displayed on the page before clicking to open the lightbox, which wasn't the behavior I wanted.

Instead of looking for "lightboxes", I focused on "carousels" and stumbled upon this code excerpt on CodePen for a responsive carousel using the Swiper.js library. At that point I was mostly fueled by pure stubbornness so I figured it was just easier to bypass markdown and use the library directly instead of looking for a ready-made package.

Here's the code I wrote (Javascript + CSS + HTML)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{% extends "base.html" %}

{% block libs %}
    {{ super() }}
    <script src="https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.js"></script>
{% endblock libs %}

{% block scripts %}
    {{ super() }}
    <script>
    const swiper = new Swiper('.swiper', {
        // Optional parameters
        loop: true,
        slidesPerView: 2,
        spaceBetween: 20,
        centeredSlides: true,
        grabCursor: true,
        // Navigation arrows
        navigation: {
            nextEl: '.swiper-button-next',
            prevEl: '.swiper-button-prev',
        },
        pagination: {
            el: ".swiper-pagination",
            clickable: true
        },
    });
    </script>
{% endblock scripts %}

50
51
52
53
54
55
56
57
58
theme:

.....

    custom_dir: 'overrides'

extra_css:
- https://cdn.jsdelivr.net/npm/swiper@8/swiper-bundle.min.css
- stylesheets/extra.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
/** Add your extra/custom CSS classes below */

.swiper {
max-width: 75rem;
width: 100%;
padding: 4rem 2rem;
margin: 0 auto;
}

.swiper-pagination-bullet {
        opacity: 0.2;
        background: var(--md-default-fg-color);
}
.swiper-pagination-bullet-active {
        background: var(--md-default-fg-color);
        opacity: 1;
}

.swiper-pagination {
    position: relative;
}

.swiper-button-next,
.swiper-button-prev {
    background-image: none;
    background-size: 0;
    background-repeat: no-repeat;
    background-position: 0;
    color: var(--md-default-fg-color);

}      

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<!-- Slider main container -->
<div class="swiper">
<!-- Additional required wrapper -->
<div class="swiper-wrapper">
    <!-- Slides -->
    <div class="swiper-slide">
        <img src="https://source.unsplash.com/1280x720/?turtle" alt="Image Slider">
        Image 1
    </div>
    <div class="swiper-slide">
        <img src="https://source.unsplash.com/1280x720/?chameleon" alt="Image Slider">
        Image 2
    </div>
    <div class="swiper-slide">
        <img src="https://source.unsplash.com/1280x720/?snail" alt="Image Slider">
        Image 3
    </div>
</div>  
<div class="swiper-pagination"></div>
<div class="swiper-button-prev"></div>
<div class="swiper-button-next"></div>
</div>

And here is the result, featuring three random pictures from Unsplash:

Image Slider This slider is reactive and changes size dynamically based on screen dimensions. Pictures can be navigated by clicking on the previous/next arrows, on the pagination dots below, or even by grabbing/swiping.
Image Slider I think this will be very convenient to document processes (with pictures in chronological order), writing tutorials (one step at a time), listing projects I'm interested in, etc. without making the page too busy.
Image Slider The only issue is that I'll have to write directly in HTML and won't be able to use markdowns in captions. Ideally if I had more time I could write some code that would interpret custom markdown but this has much lower priority than writing the actual content of the documentation!
Last update: 2022-09-27