@@ -25,13 +25,13 @@ If you use Terminal often and you know what a package manager is (such as apt-ge
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`).
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 (output 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`).
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 (output should look similar to `pip 1.5.2`).
```bash
pip --version
...
...
@@ -76,7 +76,7 @@ The following file structure should have been created inside.
- 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.
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 as text files in Markdown format.
Edit the `mkdocs.yml` file to change the name of your website.
...
...
@@ -139,7 +139,7 @@ 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.
This will enter the `docs` directory, then use `mkdir` (make directory) for assignments and create empty files with the `touch` command (you add more filenames, separating them with a space, to create many files with one command).
## Step 5. Adding Content
...
...
@@ -160,19 +160,9 @@ I am a humman.
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.
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. Also, the first heading (About) is going to be the label of the section in the MkDocs website menu.
```
<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.
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. There are many more uses of it. Try [Deckset](https://www.deckset.com/) or [Remark](https://github.com/gnab/remark) to make presentations. Fast.
**final-project.md**
...
...
@@ -183,7 +173,15 @@ This page describes my final project idea. It is going to be an automated fishin
```
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`.
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`.
For this to work you also need to create a directory `fabacademy-docs/images` and put the `final-project.jpg` image in there.
**assignments/week01.md**
...
...
@@ -193,7 +191,20 @@ Here we use Markdown way of inserting images. The basic syntax is `![]()` (excla
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.
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 directory level.
## Step 6. Final Test
Now you should have a ready MkDocs skeleton for your Fab Academy documentation website. Do test and see how it looks like. Navigate to the root of the `fabacademy-docs` directory and use the following command to launch the MkDocs development server.
```
mkdocs serve
```
Open your web browser (Firefox, Chrome or other) and enter **http://localhost:8000**. You should see the following output.
## Problems Faced and Solutions
...
...
@@ -202,11 +213,13 @@ Now that you have a basic skeleton for documenting your Fab Academy progress, th
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)
(More on that in a following tutorial)
Another problem you will possibly face is the integration of this MkDocs site with the Fab Academy GitLab.
(More on that later)
(More on that in a following tutorial)
You might also want to tweak the appearance of your website. Use the official [MkDocs](https://www.mkdocs.org/) documentation website. You should be able to find solutions there.
