Practising the previous commands helped me to remember how the commands are used, because the last time I used them was the last year and I forget the syntax of some of them.

MKDocs

MKDocs is a Python-based site generator that combines Markdown with Jinja2 templates to produce websites. Documentation source files are written in Markdown but configured with a YAML file.

I programmed HTML a long time ago and I remember almost nothing. Thus, I took the decision to start my website with MKDocs because the given repository has an initial setup to work with this generator.

Installing Atom

To create or modify the files that we need in MKDocs it is necessary to install a text editor. So far I have used Atom and Visual Studio but I think atom is better for HTML programming. Atom is a text editor cross-platform editor which means that in the offical page of Atom you can dowload the software and install it.

Setting up MKDocs on Ubuntu

In order to modified the files and update the given template of MKDocs, we need to install Python 3 or verify that it is installed. In my case, I am using Ubuntu and there is no need to install Python 3 because it is installed by default. Nevertheless, we can verify that it is installed with the following command:

				python3
			

If the command window displays the Python version that Ubuntu is using, it means that it is correctly installed. Therefore, the next step is to install pip which is a python package manager with the following command:

				sudo apt install python3-pip
			

Once pip has been installed, it is time to install MKDocs in Ubuntu with the following command:

				sudo apt install mkdocs
			

Since the template is using a theme called "material", it is necessary to install it with the following command:

				sudo apt install mkdocs-material
			

The last thing to install is the plugin for the localized date because the template is using it. The plugin can be installed with:

				pip3 install mkdocs-git-revision-date-localized-plugin
			

Once the plugin has been installed, Atom can be opened to start the edition of the website tipying the following in the terminal:

				atom .
			

The first file that has to be modified is the mkdocs.yml which contains the general information about the website

After the file is saved with Ctrl + s, the project can be previewed in the browser at "http://localhost:8000" using the command:

				mkdocs serve
			

Everytime that a file is modified or created in Atom, it is neccesary to save the changes and the website will be automatically updated. In case you do not see the changes, you can refresh the website.

Learning MKDocs and HTML

Since I did not remember a lot of HTML, I followed the given tutorial in the BootCamp and the HTML basic tutorial of the Fab Academy to create the first version of my website with HTML. These tutorials help me to realized that HTML is not as hard as I remembered or perhaps it is because nowadays we have more resources than 10 years ago when I had my first approach to HTML. At the end I was able to wrote my first HTML version which is shown below:

After I tried out HTML, I used a Markdown tutorial and a Markdown Cheat Sheet to learn how to document in MKDocs. So far, I am loving MKDocs since it allows you to use Markdown and HTML syntax in the same file. This characteristic is really useful because sometimes is easier to program with one language than the other or some instructions allow you to have more control over the website. After a few hours practising I was able to finish the first assignment about Project Management.

Most frequent syntax in Markdown and HTML

Once I practised with MKDocs, I realized that there are a few syntaxes that we need to learn since they are the most frequent used.Thus, I created the following table that contains those syntaxes in Markdown and HTML.

#H1
##H2
###H3

<h1>H1</h1>
<h2>H2</h2>
<h3>H3</h3>

<b>bold text</b>

<i>italicized text</i>

<blockquote>blockquote
text</blockquote>

1. First item
2. Second item
3. Third item

<ol>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ol>

- First item
- Second item
- Third item

<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>

<code>code text</code>

<a href="https://
www.name.com">title</a>

<img src="image.jpg"
alt="alt text">

HTML5UP

After a lot of thinking about if I wanted to continue with the given template or use HTML. I found out about HTML5 UP which is a relly good website where you can obtain a whole template in HTML and you can just change the information that you want wherever you want. I chose a template named Dimension which is a really good looking website and which I think can be a good start to build my website.

Nevertheless, it is not as easy as it sounds I had to make changes in my local repository and in GitLab. The first thing I did was to create a backup in case I lost the data or simply because I did not like it. Afterwards, I move to the folder where my website is saved with:

cd FabAcademy/My_WebPage/cuautli-garcia/

Now, it is time to erase all the visible and hidden files with the following comands:

rm -rf ./*
rm .gitignore .gitlab-ci.yml

If the files were erased the folder with your name must be empty and we can copy the downloaded files from the template that was chosen. Since, all the old files were erased and new files were copied. I added and verified that the files were changed with:

git add .
git status

The previous image shows in green the removed files and also the new files which means that everything worked as planned. Then, I proceed to commit and push the files to my GitLab account with:

git commit -m "Uploading new website"
git push

Now that all the files are uploaded in GitLab, it is time to create the .yml file which is used to tell what type of files we have (HTML). Thus, we need to open the repository in GitLab and click in "New file" as shown in following picture:

A new windows was openned where we need to select a template, the language, write a comment to save the file and click in "Commit changes". These steps can be seen in the next image with number to identify the order.

Useful Resources

• Git
• MKDocs
• Markdown
• Markdown Cheat Sheet
• HTML5 UP
• Atom

Go Back