Commit eaa453c9 by Krisjanis Rijnieks

Add MkDocs tutorial

parent a66520b5
Pipeline #49305 passed with stage
in 4 minutes 25 seconds
# Tutorial title
- Original tutorial by: Krisjanis Rijnieks
- Your lab name: Aalto Fablab
- License: CC-SA-BY
- Last Review Date: 18 Jan 2019
- Last Modified by: Krisjanis Rijnieks
## Summary
This tutorial describes how to use [MkDocs](https://www.mkdocs.org) to build a skeleton for your Fab Academy documentation website.
HTML, CSS and JavaScript can take a long time to learn and many years to master. If you have no or little background in it, choose MkDocs and learn [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
MkDocs is an open source static website generator. Text files written in Markdown are used as input, complex HTML is generated as output.
## Step 1. Installing MkDocs
To be able to build your documentation on your personal computer, you should install MkDocs on it. That will give you the opportunity to edit Markdown and preview final website side-by-side on your desktop (or laptop) computer.
If you use Terminal often and you know what a package manager is (such as apt-get, dnf, homebrew, yum, chocolatey, etc.), try to install mkdocs with it. Below is an example with [Homebrew](https://brew.sh/) on MacOS X.
```bash
brew install mkdocs
```
You can also install MkDocs with Python. However make sure that you have Python installed first. Use the following line. It should output the version of Python installed on your system (should look similar to `Python 2.7.2`).
```bash
python --version
```
You will also need the Pip package manager. Test if you have it first with the command below. It should output the version of your Pip (similar to `pip 1.5.2`).
```bash
pip --version
```
If you do not have Python and/or Pip installed, follow instructions on the [MkDocs website](https://www.mkdocs.org/#installation) to install them first.
With Python and Pip installed, use the following command to install MkDocs.
```bash
pip install mkdocs
```
Confirm successfull installation of MkDocs by using the command below. It should output the current version of MkDocs installed on your system (such as `mkdocs, version 0.15.3`).
```bash
mkdocs --version
```
## Step 2. Creating new MkDocs Project
If you have a ready MkDocs solution on your GitLab repository already, you can use that. However this tutorial will explain a bit more how it works.
In Terminal navigate to directory where you want to create your documentation website project. In my case I will assume it is `/home/kris`. Use the following command to create a new project.
```
mkdocs new fabacademy-docs
```
If you use `ls` (list) you will see a new directory `fabacademy-docs`. Use `cd` (change directory) to enter it.
```
cd fabacademy-docs
```
The following file structure should have been created inside.
```
- docs
- index.md
- mkdocs.yml
```
The `mkdocs.yml` file is a configuration file for your newly created MkDocs project. The `docs` directory is where you will write your actual documentation in Markdown format.
Edit the `mkdocs.yml` file to change the name of your website.
```
site_name: Kris Does Fab Academy
```
## Step 3. Launching Test Server
MkDocs can convert Markdown to HTML website and act as a webserver so you can see how changes will look on the generated website almost on-the-fly. Use the following command to try it out.
```
mkdocs serve
```
You should see interesting things showing up in your terminal.
```
INFO - Building documentation...
INFO - Cleaning site directory
[I 190118 22:15:30 server:292] Serving on http://127.0.0.1:8000
[I 190118 22:15:30 handlers:59] Start watching changes
[I 190118 22:15:30 handlers:61] Start detecting changes
```
Here you see that a server is started for IP address `127.0.0.1` and the MkDocs web server is accepting connections on port `8000`. Usually the address `127.0.0.1` translates to `localhost` and you should be able to see your new MkDocs website by using `http://localhost:8000` as the website address.
![First MkDocs server run](mkdocs/first-run.jpg)
## Step 4. Adding Structure
Usually a Fab Academy documentation website will have a page about you, your final project and assignments. Let's make a basic structure that will be enough for the first week of the academy (and probably for the whole course).
```
- About
- Final Project
- Assignments
- Week 01
```
The structure above is what we have to translate to a directory structure under `docs`.
```
- docs
- index.md
- final-project.md
- assignments
- week01.md
```
Note the `index.md` file. It will translate to `index.html` when HTML is going to be generated. It is usually the file name your web browser is going to look for first when loading a web page from a server. It should be there as an entry point to your documentation website. It will also be our **About** page.
Create this structure either by using Terminal or the file browser of your system. You can use the following commands in terminal.
```
cd docs
mkdir assignments
touch final-project.md assignments/week01.md
```
This will enter the `docs` directory, then use `mkdir` (make directory) for assignments and create empty files with the `touch` command.
## Step 5. Adding Content
At this point you should open your favorite text editor and start adding content. Try adding content similar to the following in your `index.md` file.
```
# About
My name is Kris and this is my Fab Academy documentation website. This page will tell you more who I am and what are my intentions.
## Who am I
I am a humman.
## My Intentions
I want to build a CNC machine.
```
This is Markdown. Every line with a `#` in front of it is going to become wrapped in `<h1>` (heading 1) tags. In this case our `# Hello!` will become the following. Lines starting with `##` will be translated to `<h2>` (heading 2) tags.
```
<h1>Hello!</h1>
<p>My name is Kris and this is my Fab Academy documentation website. This page will tell you more who I am and what are my intentions.</p>
<h2>Who am I</h2>
...
```
Check the [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to learn its syntax. It is one of the easiest markup languages to learn.
**final-project.md**
```
# Final Project
This page describes my final project idea. It is going to be an automated fishing system. I have made a first working prototype with an Arduino, but the wiring is all over the place and I have decided to improve.
![Final Project Sketch](images/final-project.jpg)
```
Here we use Markdown way of inserting images. The basic syntax is `![]()` (exclamation mark, square brackets, round brackets). Explamation mark tells MkDocs that there will be an image. In the square brackets we add text that should describe the image and will be seen if the image will fail to show up for whatever reason. Finally in the round brackets we enter the path to the image. In this case I made a new directory `docs/images` where I placed a image called `final-project.jpg`.
**assignments/week01.md**
```
# Week 01. Principles and Practices
The first week of Fab Academy! I did a sketch of my project and added it to the [Final Project](../final-project.md) page.
```
Here I use a concept that is called the **relative link**. Notice the `../` part before `final-project.md`. Since the `week01.md` file is in the `assignments` directory, we have to tell MkDocs to look for the `final-project.md` file one level up from where `week01.md` file is. `../` does that - it is a common way to point to a directory one level up from the current one.
## Problems Faced and Solutions
Now that you have a basic skeleton for documenting your Fab Academy progress, there will be a few challenges ahead.
Adding videos is one challenge. The consistent way is to add videos as files and use the `<video>` tag in Markdown (yes, HTML is allowed in Markdown) to load it as HTML5 video. Loading YouTube or Vimeo videos might be a bit more complicated. There are also Python Markdown plugins that can be used.
(More on that later)
Another problem you will possibly face is the integration of this MkDocs site with the Fab Academy GitLab.
(More on that later)
## Sources
- [MkDocs Website](https://www.mkdocs.org)
- [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
## Files
- [MkDocs Project](fabacademy-docs.zip)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment