Skip to content

How to Document Your Work

This guide explains why and how to document your work in this microelectronics course using MkDocs and Markdown.

Why Open Source Your Work?

During the course you should be documenting your learnings and sharing them by making your work public, so that classmates can learn from your approaches and solutions. Your documentation will also be used by instructors to evaluator your assignments.

What is MkDocs?

Your personal website is build using a tool called MkDocs, which is a static site generator build for documentation projects. It converts files written in Markdown into a beautiful, searchable website. For this course, we've pre-configured an MkDocs site structure for you. Mkdocs supports theme, which by default we are using the Material for MkDocs theme.

What is Markdown?

Markdown is a lightweight markup language that lets you format text using simple, readable syntax. It's designed to be easy to write and easy to read in its plain text form.

Basic Markdown Examples

Headings

# Main Title
## Section Title
### Subsection Title

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
`Code snippet`

Lists

- Unordered item 1
- Unordered item 2

1. Ordered item 1
2. Ordered item 2

[Visual Link text](https://example.com)

Images

![Alt text](../foldername/image.jpg)

Code Blocks

```python
def hello_world():
    print("Hello, World!")

#### Tables
```markdown
| Column 1 | Column 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

GitLab Platform

We host a GitLab instance where your documentation project is stored. This platform provides tracks changes to your files through a system called GIT. Every change you make is stored in a commit which then triggers a server process, called CI pipeline, which will build your website and publish it on a public address.

Access and Login

Our GitLab instance uses a centralized identity provider for authentication using the network fablabs.io platform. This login flow ensures that you can use the same credentials across all our course platforms.

Three Ways to Edit Your Website

We provide three different methods to edit your personal website, depending on your comfort level using GIT:

Our custom web editor browser app is designed to keep things simple by only showing your a visual markdown editor and a button to save your changes. Drag and drop images and files into your document. This leaves the GIT system completely hidden from you.

How to Use

  1. Open https://editor.fabcloud.org/ in your browser.
    • We suggest opening the editor app in the tools container web browser, so you have acces to you files.
  2. Login with your fabcloud credentials (provided in an email).
  3. Select your microelectronics-2026 personal project from the list (you may have more than one project listed).
  4. Navigate to the file you want to edit.
  5. Make changes using the Markdown editor.
  6. Click "Save" - changes are automatically committed to Git.
  7. Drag-drop images into the markdown editor and images will get uploaded the refresh code added to your file.
    • FYI, images will automatically get resized and compress to work best with websites.

Method 2: GitLab Web Interface (Basic GIT)

You can also edit your files directly in the GitLab web interface using your own local browser.

How to Use

  1. Navigate to your project in GitLab.
  2. Open the Web IDE by clicking the "Web IDE" button under the blue "Code" button.
  3. Navigate to the file you want to edit.
  4. Make your changes.
  5. Then select the commits tab to see your changes and commit them.

Method 3: Local Development (Advanced)

Clone the repository in your tools container or locally on your machine and work with your preferred tools.

Setup Steps

  1. Install Git on your local machine if not already installed

  2. Create a ssh key pair and add it to your GitLab account

    a. If in the tool container, you can do this: 

    ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -f /foss/design/.ssh/id_rsa
    b. No passphrase is needed, leave empty when prompted. c. Copy the public key to your clipboard: 
    cat /foss/design/.ssh/id_rsa.pub
    d. Add the public key to your GitLab account.

  3. Clone your repository:

    a. If in the tool container: 

    GIT_SSH_COMMAND="ssh -i /foss/design/.ssh/id_rsa" git clone git@gitlab.fabcloud.org:path/to/your-project-name.git
cd your-project-name

    b. If locally on your machine: 

    git clone git@gitlab.fabcloud.org:path/to/your-project-name.git
cd your-project-name

  4. Config your commit name

    git config user.name "Your Name"
git config user.email "your_email@example.com"

  5. Install MkDocs (optional, for local preview): 

    pip -r requirements.txt

  6. Run local server (optional): 
    mkdocs serve
    Your site will be available at http://127.0.0.1:8000

Workflow

Edit files with your preverred editor, then commit and push changes:

# These commands to add your changed files
git add .
git commit -m "Update documentation"

# if in the tool container
export GIT_SSH_COMMAND="ssh -i /foss/design/.ssh/id_rsa" git push
# else locally just
git push