Using Markdown for My Page

At first, I thought I would use my HTML, CSS, and Bootstrap skills to build my page from scratch. However, I quickly realized that I didn’t have enough time to focus on this, since I only had one week and many assignments.

To save time, I decided to use Markdown, which is much faster and simpler than HTML and CSS for creating a functional website.

Markdown Structure

From the structure above, I learned that:

All my documentation files needed to be placed inside the docs folder.

The index.md file serves as the main page of my website.

Markdown does not require complex coding like HTML, which made it easier for me to focus on content instead of design. I found it very useful for working quickly and efficiently.

Deploying Steps

To set up my site, I used the following template, which made my work much easier: MkDocs Template

After editing my files, I used Git commands to upload (push) my work to my repository: git commands

Important configaration

While setting up my website, I learned that some important files must be placed in the root folder of the repository (not inside the docs folder).

These files include:

mkdocs.yml

.gitignore

.gitlab-ci.yml

requirements.txt

My instructor Rico reminded me to move .gitignore and mkdocs.yml out of the docs folder and into the root directory.

mkdocs.yml File

I also worked with the mkdocs.yml file. This is the configuration file for MkDocs, and it controls how the website is built and displayed.

In this file, I configured:

The site name

The navigation menu

The URL of my website

I realized that it connects all the Markdown pages together and defines how the final website looks.

I used the template below which easen my work,

.gitlab-ci.yml

I updated the .gitlab-ci.yml file so GitLab can automatically build and publish my website whenever I push changes.

This file: image: python:3.11-slim

before_script: install Git for the mkdocs revision plugin - time apt update && apt-get install -y git Install mkdocs and theme - time pip install -r requirements.txt

test: stage: test script: - time mkdocs build –site-dir test artifacts: paths: - test rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH when: never

pages: stage: deploy variables: ENABLED_GIT_REVISION_DATE: “true” GIT_DEPTH: 0 script: - time mkdocs build –site-dir public artifacts: paths: - public rules: - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

requirements.txt

I also added a requirements.txt file in the root folder. This file lists the Python packages needed to build the MkDocs site:

Documentation static site generator mkdocs ~= 1.4

Add your custom theme if not inside a theme_dir (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes) mkdocs-material ~= 9.0

Plugins mkdocs-git-revision-date-localized-plugin ~= 1.1.0

This ensures the server installs the correct tools during deployment.

After editing my files i used the git commands git commands to push to my repository.

Today, I successfully completed:

Git setup

MkDocs installation and setup

Markdown-based website creation

Website configuration using mkdocs.yml

Automatic deployment using GitLab CI

This gave me a strong foundation for documenting the rest of my Fab Academy journey.