Skip to content

Organising and Blogging

The titles of the two different subjects of the first fabacademy week were a bit confucing to me at first. Principles and practices were interpreted by me as to learn how to work with all basic systems in fabacademy. It turned out just the other way: project management was dealing with that subject. As always: just read carefully what is written, so that’s lesson one for me. ;-P

Site Structure

After learning a bit about markdown and mkdocs I noticed that I wasn’t very pleased with the structure of my fabacademy site. The predefined set-up is just representing the sequence of our activities from Januari to June. In my opnion the structure should echo the content of my journey. I decided to group the content into subjects as you can see in the menu.

Because this might cause problems for instructors or peers that want to review my assignments, I have created an extra page with a weekly overview and links to the various parts in the pages that are dealing with that specific topic. Preferably I would like to tag them too, but I don’t know yet how to do that or if it’s even possible with mkdocs.

For the structure I mentioned I have regrouped the content into the topics as you can see in the top menu. As an example: they allow me to group all my learnings about electronic design. I expect that in the coming months my experience on this topic will grow. Having a direct view on issues from an earlier week shows a natural and logical evolution of my knowledge.

For now these categories seem useful, but in due time they might change. That’s also how proceeding insights work.

Working with Markdown and Mkdocs

New to me are Markdown and mkdocs. I have some basic understanding of HTML, I built my company website by just copying one that was made by my wife and inserting my own content. For mkdocs I had a lot of trouble understanding how some basics work. The documentation you may find is not always clear about the underlaying principles. Below are some issues I found and how I dealt with them.

Because I wanted to change something in the Table of Content (ToC) at first I changed the names of sub-folders in the docs directory. How this table is built is not clear in the documentation of mkdocs, markdown or the material-theme that is used in mkdocs. By experimenting a bit I found out:

  • the order of the ToC is defined by the filenames and automatically arranged in alphabetic order;
  • the headers are drawn from the H1 header in that same file;
  • the order in the top menu is also alphabetically ordered, but here from the sub-folder names;
  • you can’t change the order because the folder names are also exactly the header names;
  • the materials theme automatically replaces the first character into a capital and replaces dashes by a space.

Tweaking the Theme

Some fonts and colors were not what I liked. This is well documented, so I changed some features in the mkdocs.yml file:

theme:
    name: material
    palette:
        # try other colors https://squidfunk.github.io/mkdocs-material/getting-started/#primary-colors
        scheme: slate
        primary: cyan
        accent: yellow
    font:
        # See available fonts at https://fonts.google.com/
        text: Roboto Slab
        code: Ubuntu Mono

Because I wanted the headers look different I used an extra style sheet by adding the following lines in the file: 

extra_css:
  - styletweak.css

But it didn’t do everything I wanted. Apparently the color of the H1 is defined by the theme and can’t be changed. For the H2 I wanted to change the weight of the font, but that also wasn’t possible. So trying this in my css-file didn’t work:

h1 {
    font-family: "Futura";
    color:rgb(255, 0, 0)
}
h2 {
    font-family: "Futura";
    color:rgb(109, 250, 255);
    font-weight: bold;
}

This css drew the same result:

h1 {
    font-family: "Futura";
}
h2 {
    font-family: "Futura";
    color:rgb(109, 250, 255);
}

So that’s what I kept for now.

Help from others deserves credit, so I included some links to my content. Annoying was that links open in the active window. Official documentation said it was not possible to make markdown add :target="_blank" W3schools however suggested that adding {:target="_blank"} might work sometimes, depending on the site generator. And yes it does for mkdocs!

Learnings and Resources

The first week already got me quite frustrated sometimes. The instructors are often focused on “how to do it”. Usually they also address the “why to do it”, but the basic principles of the “how” are not enough clarified for a layman like me. Unluckily most documentation about markdown or mkdocs isn’t very clear either.

For practical information the most useful sources to me were:

I didn’t put footage into my documentation at the start, but did figure out how to in week 4. I downloaded ffmpeg which is widely used to convert, merge, stream or do anything to adapt your footage. I found all documentation on ffmpeg.org. This documentation is not very comprehensible for non-experts, but it was good enough for me to come up with a simple conversion line:

ffmpeg -i milling.mov -s 584x640 milling.mp4

I haven’t scripted this for film or pictures. For now I prefer to do it manually, becuase I want to be able to keep in control of the framing. Most pictures are oversized snapshots that I want to crop afterwards.

Last update: March 2, 2022
Back to top