Skip to content

Contribute

Overview⇝

Welcome! This is a general guide for contributing to this website.

This website is created using MkDocs Material which is an open source static site generator particularly useful for documentation. Content in MkDocs Material is written in Markdown, a markup language which is easier to understand and edit than HTML, making content formatting more accessible.

MkDocs Material References

Mkdocs Material has extensive documentation, so if you get stuck, it is a good idea to check there to see if the issue you are dealing with is explained in their documentation.

It is okay for contributors to make small changes to the MDEF website via GitHub using a pull request without testing locally. Some small changes might include updating a faculty bio, changing a photo, or fixing a detail on a module page. However, larger changes are a bit more complex and should be done in a more systematic way, which will be covered in detail below.

This document will first look at some basics (Markdown guidelines, git development workflows, and local development). This foundational knowledge will allow us to move onto the specifics of major changes to this website.

After laying the groundwork, the bulk of this guide will consider three major changes that might need to be made to the MDEF website and specific guidelines on how to make these changes:

  1. Adding new module pages
  2. Adding a new faculty profile
  3. Updating the menu to reflect these changes

First though, we need to start with the basics before we can start editing. Let's get started!

Markdown⇝

Since the content of Mkdocs Materials websites is written using Markdown files, it is important that you are familiar with some Markdown basics. If you already know Markdown, you can skip to to the next section.

Using Markdown to format documents is simple, and using Markdown within MkDocs Material allows you to add all the elements that are used on this website (including more complex formatting like content tabs which we use to show schedules).

The following sub-sections will cover the Markdown basics most frequently used on this website. However, we've included some additional resources as well which offer more detailed explanations and might help with troubleshooting if you can't find an answer in this document. The tutorial suggested in the additional resources section does not take very long to complete, and it is highly recommended if you are new to Markdown.

Headings⇝

Headings on websites create a heirarchy, both for human readers as well as robot readers (like web crawlers, bots that systematically index the internet for search engines).

Headings are created using the number sign (#) with the corresponding amount of symbols equating to the heading number it will create:

Heading Markdown
H1 # Your H1 Title
H2 ## Your H2 Title
H3 ### Your H3 Title
H4 #### Your H4 Title
H5 ##### Your H5 Title
H6 ###### Your H6 Title

Important notes

  1. Note that above there is always a space after the number signs, if you don't include this space before the header title, your text will not appear as a header.
  2. There should only be one H1 on each page, this is considered a best practice and it is also logical for human readers. Importantly, using only one H1 also helps web crawlers to understand the structure of website content and can affect SEO ranking (negatively if more than one H1 is used on a page).
  3. H1 titles of most pages on this website are included in the Front Matter of the Markdown files (see below).

Paragraphs⇝

Paragraphs should be separated by a blank line. If you do not include this blank line, the content will run together. Also, there should not be tabs or spaces at the beginning of a paragraph.

Bold and italics⇝

Add emphasis with bold or italics using asterisks or underscores before and after the text to be emphasized (one for italics, two for bold, and three for bold and italics).

Example Markdown
A bold text **A bold text**
A bold text __A bold text__
An italicized text *An italicized text*
An italicized text _An italicized text_
An italicized bold text ***An italicized bold text***
An italicized bold text ___An italicized bold text___

Keep it consistent

Consistency in your formatting is important. This website has been built largely using two asterisks for bold and one underscore for italics. Choose your preference, but be consistent. It makes reading your Markdown documents easier for others.

Lists⇝

Unordered lists⇝

Unordered lists (with bullet points) can be created with a number of symbols. The typical symbol is a dash (-), though other symbols like asterisks (*) or plus signs (+) can be used. You should follow the symbol by a space and then the content.

Keep it consistent

It is best to be consistent with which symbols you use, both in individual lists as well as between documents.

Ordered lists⇝

Ordered lists (with numbers) are created with numbers followed by periods, a space, and then your content.

More complex lists⇝

You can create nested lists within both types of lists using a new line followed by a tab, and then whichever structure you desire for the nested list.

List examples in Markdown
**Examples of lists**

_Unordered list with nested unordered list_

- First item
- Second item
- Third item
    - Indented item
    - Indented item
- Fourth item

_Ordered list with nested ordered list_

1. First item
2. Second item
3. Third item
    1. Indented item
    2. Indented item
4. Fourth item

_Ordered list with nested unordered list_

1. First item
2. Second item
3. Third item
    - Indented item
    - Indented item
4. Fourth item

Examples of lists

Unordered list with nested unordered list

  • First item
  • Second item
  • Third item
    • Indented item
    • Indented item
  • Fourth item

Ordered list with nested ordered list

  1. First item
  2. Second item
  3. Third item
    1. Indented item
    2. Indented item
  4. Fourth item

Ordered list with nested unordered list

  1. First item
  2. Second item
  3. Third item
    • Indented item
    • Indented item
  4. Fourth item

Don't break the list

Lists can be broken if the formatting is not done correctly. It is possible to add images, admonitions, and block quotes within lists, but all of these must be indented within the list so that the heirarchy is not broken (which would reset numbering in the case of ordered lists.)

Ordered list with admonitions

  1. First item

    Admonition that doesn't breaks the list

  2. Second item

  3. Third item

Admonition that breaks the list

  1. Fourth item

Adding links is as simple as including the text you want to appear as a link within square brackets like [this] followed by the URL within parenthesis like (this).

A complete example of a link would be:

[A simple link](https://fablabbcn.org/)

The result would look like this:

A simple link

Troubleshooting

Notice that there is no space between the square brackets and the parentesis.

This is important, if there is a space your link will not work!

Relative links are also possible, and should be formatted with an absolute path. An example of this would be the following:

[A link to the faculty page](/faculty)

A link to the faculty page

Images⇝

Images are added starting with an exclamation point (!), followed by square brackets [] with an alt text. Then a set of parentheses with the path to the image, either with a URL or a relative link (we keep our images in the /assets folder).

What is an alt text and why should I include one?

The alt text is not mandatory, and the square brackets can be left blank. However, including an alt text is a best pratice for a number of reasons.

  1. The alt text functions as a description in case something goes wrong with loading the image.
  2. It is indexed by search engine bots to better understand image and page content.
  3. The alt text can be read aloud by programs called screen readers which are used by people with visual impairments and low vision.

Takeaway: Including an alt text is important for accessiblity and general best practices.

Here is an example followed by the expected output:

![Banner image for Agriculture Zero module](/assets/images/2023-24/year-1/t-1/agriculture-zero.jpg)

Banner image for Agriculture Zero module

Images can also be links! All you have to do to make an image a link to include the entire line within a set of square brackets followed by the URL within parenthesis, just like we saw within the link examples above.

[![Banner image for Agriculture Zero module](/assets/images/2023-24/year-1/t-1/agriculture-zero.jpg)](/2023-24/year-1/t1/agriculture-zero/)

Banner image for Agriculture Zero module

Additional resources for markdown⇝

Additional formatting with MkDocs Material⇝

Other MkDocs specific formatting options that are used throughout this website include:

Each of these three formatting options has a specific use case on the MDEF website. All three are described in detail below.

MkDocs Material has an overall reference page which provides very thorough documentation to help users format their documents easily. On the MDEF website, some of the visual elements have been edited for stylistic reasons, but their functionality should not change.

Branches and pull requests⇝

All contributions should be made with a pull request which requires the creation of a new branch.

What is a branch?

git-scm explains a branch like this:

Branching means you diverge from the main line of development and continue to do work without messing with that main line.

Read more on about branches on git-scm book

What is a pull request?

GitHub explains a pull request like this:

A pull request is a proposal to merge a set of changes from one branch into another. In a pull request, collaborators can review and discuss the proposed set of changes before they integrate the changes into the main codebase. Pull requests display the differences, or diffs, between the content in the source branch and the content in the target branch.

Read more on about pull requests on GitHub.

By using pull requests, we can assure that the live version of the website does not crash, have broken links, or material that is not ready to be published. Large changes can be grouped together and changed can be lauched at the same time, for example, releasing the module pages for a new term.

Contribution requirements⇝

In general, only maintainers and admins have the permission to make direct changes to the main branch. The general process is to open a pull request on the git repository. If you are not part of the repository, you can always create a fork and do the pull request from there.

Big changes can create big problems

For small changes, it is fine to edit on the GitHub interface. However, we do not recommend this for bigger changes as they could break the site.

If you are editing on the GitHub interface, anyone can contribute to files through a pull request, either as a fork or on the repository itself. When you edit an existing file and commit changes, you will be prompted to create a branch for your changes, and you will be redirected to an open pull request page. You can do as many commits as you want on this branch and they will be automatically added to your pull request. If you are still making changes, you can convert your pull request to a draft and then mark it as "ready for review" when you are ready.

Keep it simple

You don't need to create a new branch for each change. Once you create the branch and have the related pull request, make sure that additional related changes are done within the same branch. As mentioned above, additional commits on the same branch will be added to your pull request.

Testing locally⇝

Testing locally is recommended for big changes, for example, adding new features, or large amounts of new material. This will require some basic knowledge of command line, python, and git.

Setting up your work environment⇝

  1. Clone the repository: 
    git clone git@github.com:fablabbcn/mdef-docs.git

  2. Install Python 3:

    Python newies! Read the following guide.

  3. Install requirements: 

    pip install -r requirements.txt
    In Windows if it fails use pip install -r requirements.txt --user instead.

  4. Serve the mkdocs site and make your edits: 

    mkdocs serve

    When mkdocs is serving, a line with the local host address will appear in the commandline. Typically, http://127.0.0.1:8000

Contribute to the main repository

Once you are doing making your changes, you can push to a branch:

git checkout -b <Your branch name>
This will create a new branch where you can add, commit, and then push your changes to be reviewed.

MDEF website specifics⇝

Adding new module pages⇝

For new module pages, you will need to create a new Markdown file. This file should be named index.md and it will be saved within a folder named to reflect the module, for instance design-studio-01 and design-with-others are both folders with a single markdown file both named index.md. This structure allows the pages to be loaded without a .md extension in the browser window.

Folder structures and changes

The structure of these folders is important to maintain. If folders or files are moved, their corresponding locations have to be correctly updated in the mkdocs.yml file to ensure that there are not broken links in the menu.

Pages for MDEF modules follow a specific structure. The headings should be used consistently since all H2 headers appear in the “Table of contents” or secondary menu (in the lower right corner of the screen).

Likewise, the Front Matter of these pages provides the structure that creates the banners with course details. First, we will look at the Front Matter, as it is always at the top of a new Markdown file. Then we will look at the content and what it includes.

Front Matter for module pages⇝

Front Matter is a list of keys or fields at the top of a document that don't necessarily show up automatically on the page. Some are native to MkDocs and others have been created based on the needs of the MDEF website. The Front Matter of the page goes at the very top of a Markdown document. Here are the keys used in MDEF module pages followed by a description of each of them and then an example filled out correctly.

Front Matter for module pages
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
---
title:
page_type:
track:
course_type:
feature_img:
img_caption:
faculty:
    - 
ects:
---

Understanding the Front Matter keys used on module pages

Keys in Front Matter are the different fields that need to be filled in, for example: title:, page_type: or faculty:

title: This is your H1, the title of the course in the case of the MDEF modules. This title will appear on top of your banner image. It should not be excessively long.

page_type: For MDEF modules this will always be course, written in lowercase.

track: Track types include: Application, Reflection, Exploration, and Instrumentation. When written in the Front Matter, make sure the track names are written correctly and with the first letter capitalized. If this is not done correctly, the corresponding icon will not appear properly in your intro banner and the course will not be included in module lists, like this one.

course_type: The course types are less rigid in their formatting than the tracks. They will appear at the top of the banner image next to the track type written just as they are input into this field (respecting capitalization, etc.). The original course types agreed upon are: workshop, seminar, short course, and long course, with only one course type being selected under ideal conditions. These should be written with the first letter capitalized to respect formatting guidelines, but on a technical level not doing so will not produce an error.

feature_img: The featured image will appear as the banner image on a module page. The image will automatically be cropped to a 16/9 aspect ratio cropping evenly, thus prioritizing the center of the image and standardizing the sizes of the images without additional work. Likewise, the image has a color overlay for stylistic purposes, this cannot be changed. To define a featured image, you need to define a relative path as described in the image section of this guide.

Saving images

All images should be saved in the assets folder under images to maintain order. For module courses, these images are saved in the corresponding year, and then term. An example of the location of featured image can be seen below in the example of Front Matter with the content filled out. Image files should be reduced to be less than 1000KB (1MB) to ensure fast loading of the page. The naming convention for these images is the name of the course in lowercase with dashes between words.

img_caption: The image caption will be added just as it is written below the module banner image. If this is left blank or simply not included, no caption will appear.

faculty: Since there can be multiple faculty on a single module, this key allows for a list of values, so it has a slightly different format. In this case, even if there is a single faculty member to list, a line break is needed, followed by a tab, dash (-), a space, and then the faculty name. The format of the faculty name should be firstname-lastname. (See the example below). Naming conventions correspond to the faculty files, so these should match exactly. This will be covered later in the section on adding a new faculty member.

ects: This is the amount of credits that this course is accredited for.

Troubleshooting Front Matter on module pages

  1. Front Matter must start and end with three dashes (---) on their own lines.
  2. Following each key, there must be a colon (:) followed by a space. If you do not include this space, it will produce an error.
  3. Some keys can have multiple values, like in the case of faculty. Keys like this have a slightly different formatting. The values should be written each on a new line, tabbed in once, followed dash (-) and a space then the value as described above.
Example with content:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
---
title: Extended Intelligences
page_type: course
track: Exploration
course_type: Course
feature_img: /assets/images/2023-24/year-1/t-1/extended-intelligences.jpeg
img_caption: Martian Species, Estampa, 2021
faculty:
    - ramon-sanguesa
    - lucas-pena
    - pau-artigas
ects: 3
---

Expected sections within module pages⇝

{{ insert_banner() }}

Make sure you include the line {{ insert_banner() }} following the Front Matter or the banner image will not appear even if all the details are correctly filled out.

## Syllabus

Includes: Syllabus content and keywords.

EXAMPLE:

The first term Design Studio aims to create a solid ground for the students to start developing their projects. Weekly activities will be set to interlink results from the courses like their mappings, cartographies, experiments, 1st person design activities, prototypes, with their personal development plan. In order to propose an area of intervention at the end of the trimester. The Design Studio activities will consist of presentations, group activities, short exercises and personal coaching.

Keywords: Prototyping, 1st Person Research through Design, Design Space, Documentation and Communication, Design Interventions

### Learning Objectives

Includes: Learning objectives provided by faculty. If not included, this can be left blank.

### Methodological Strategies

Includes: Methodological strategies provided by faculty. If not included, this can be left blank.

## Schedule

The schedule is written in a particular format so that it appears as content tabs. In the full model markdown code listed below this formatting is modeled.

## Grading Methods

This section often makes use of a data table to show percentages and the corresponding description of how the final grade will be determined. In the full model markdown code listed below this formatting is modeled.

If no table is provided, you can include an admonition explaining that "Grading criteria will be defined by faculty during the module."

!!! info ""

    :fontawesome-solid-circle-info:{ .icon-padding-right } **Grading criteria will be defined by faculty during the module.**

Finally, the MDEF website has a custom admonition that displays the ECTS of the module. The code should be written as follows:

!!! ects "European Credit Transfer and Accumulation System (ECTS)"

    {{ ects }} ECTS

This is generated automatically

If if the Front Matter is filled out correctly, the ECTS will appear with the corresponding number of credits.

### Evaluation strategies

Includes: Evaluation strategies provided by faculty. If not included, this can be left blank.

## Additional Resources

Includes: Additional resources provided by faculty. If not included, this can be left blank. Often these resources are provided as lists with links, see the Markdown section above for guidance if necessary.

## Faculty

To call the faculty listed in the Front Matter, all you need to do is include the line:

{{ insert_faculty() }}

As long as the Front Matter has been filled out correctly and the faculty file exists, the faculty should be automatically added to the module page.

Module skeleton file⇝

 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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
---
title:
page_type:
track:
course_type:
feature_img:
img_caption:
faculty:
    - 
ects:
---

{{ insert_banner() }}

## Syllabus

**Keywords:**

### Learning Objectives

### Methodological Strategies

## Schedule

=== "DATE 1"

    CONTENT OF TAB

=== "DATE 2"

    CONTENT OF TAB

=== "DATE 3"

    CONTENT OF TAB

=== "DATE 4"

    CONTENT OF TAB

## Deliverables

## Grading Method

| Percentage  | Description                         |
| ----------- | ------------------------------------|
| XX%         | Description                         |
| XX%         | Description                         |

!!! ects "European Credit Transfer and Accumulation System (ECTS)"

    {{ ects }} ECTS

## Additional Resources

## Faculty

{{ insert_faculty() }}

Check an existing file

It is always a good idea to check an existing file if you need to model content. You can see the source code of any page of this website by clicking the view source button at the top of the page.

Here is an example of a source code page for the module Atlas of Weak Signals.

Adding new faculty⇝

  1. Create the new faculty Markdown document with the first and last name of the new faculty member (please only use one first name, and one last name)

    docs/faculty/first-last.md

  2. Add the content using the format below.

    Template for faculty biographies
    ---
name: 
role:
feature_img: /assets/images/faculty/first-last.jpeg
socials:
    email:
    website:
    linkedin:
    twitter:
    facebook:
    instagram:
    github:
---
Biography text provided by the faculty member.
    1. Unlike the file name, the name listed in the key name: can be the complete name of the faculty member as they prefer it to be written.
    2. Socials are not required, and can be left blank.
    3. Only one social profile per platform is possible.
    4. Email format is just the email address (i.e. bob@burgers.net)
    5. Social media links need a complete URL (i.e. https://twitter.com/tomasdiez)

  3. Add the feature_img to the correct folder with the same naming structure as the Markdown file and make sure that the file name is correctly reflected in the Mardown file. For instance, for the faculty first-last example from above, feature_img should read:

    feature_img: /assets/images/faculty/first-last.jpeg

    Next, make sure that first-last.jpeg exists in the /assets/images/faculty/ directory.

  4. Add the faculty to specific courses and to the faculty page if applicable using their name in the Front Matter as we saw when creating a new module page.

Updating & adding to the menu⇝

The menu of a website built with the MkDocs Material template is defined within the mkdocs.yml file which can be found in the root folder of the repository.

The navigation structure is defined in the nav section of the document.

The first level of the navigation is defined with a single tab, dash (-), space, title, and then the path. These first level navigation items appear in the top navigation bar and currently include: Welcome!, Faculty, Students, Year 1, Year 2, and Glossary.

Here is an example of how a first level navigation item is written if it does not have a secondary menu within it: 

nav:
  ...
  - Students: 2023-24/students/index.md

However, pages which have sub-menus are written with the path on a separate line. Then, other pages within the sub-menu are listed below it with the previously explained format.

nav:
  ...
  - Year 1:
    - 2023-24/year-1/index.md
    - Calendar: 2023-24/year-1/calendar/index.md
    - Term 1:
      - 2023-24/year-1/t1/index.md
      - Design Studio 01: 2023-24/year-1/t1/design-studio-01/index.md

Pay attention to detail

As you can see, these nested lists need to follow a strict indentation format or the structure of the menu can be broken.