Skip to content

Making This Website Using mkdocs

Written on: 02.11.2025

This article addresses how I made the website and how you could give a go at mkdocs or alternatives of it.

What Does mkdocs Do?

Mkdocs is an open-source static site generator and is specifically designed for building project documentation. It converts markdown files (.md files) into a styled static documentation website. It is a python-based tool that converts the .md files into the corresponding .html and .js files with the appropriate formatting. Styling is done under a theme such as mkdocs-material, and others.

The proper structure of the .md files within directories and mkdocs.yml to apply the configurations of mkdocs make up the website.

Console commands such as the following preview the website locally and build the static website from the .md files respectively:

mkdocs serve

mkdocs build

Another very useful command is:

mkdocs gh-deploy

It deploys the website directly onto GitHub pages by uploading the built website to a gh-pages branch for hosting under the user name and repository name. I would advise using it instead of trying to set up the static built website on GitHub pages yourself.

How I Structured The Website

As you may have noticed already, the website consists of the following main sections: - CV - Projects - Blogs - Announcements - Contact - Goals - About - and the default index page that is automatically generated by mkdocs.

A clean directory structure reflecting your website's navigation is helpful but not necessary as long as you can route every navigation item properly to its corresponding .md file. The .yml should be edited accordingly (note that it is very sensitive to indentations, which have to be consistent, and not TABBED according to my experience).

The extensions I use are required to expand the avaiable .md functionalities that are built into .html files as mkdocs only has the base .md functionalities at the start.

Blogs is the most complex directory system of my website. You can study its structure as reference. blogs branches into the different sub-sections which branch out into the actual articles with image/assets folders in every directory to host the assets (makes pathing from individual .md files easier).

Exploring Alternatives to mkdocs

Easy Documentation Website Frameworks

Documentation Frameworks

Docusaurus

  • Tech: React + Markdown
  • Use case: Software documentation, open-source project sites
  • Pros:
    • Easy setup: npx create-docusaurus@latest
    • Write docs in Markdown
    • Built-in dark mode, versioning, and search (Algolia)
    • Easy deployment via GitHub Pages, Vercel, Netlify
  • Cons: React-based — may be overkill for very simple static docs
  • Get started with Docusaurus

VuePress / VitePress

  • Tech: Vue + Markdown
  • Use case: Lightweight documentation or personal sites
  • Pros:
    • Very fast, easy to configure
    • Supports Markdown + Vue components
  • Cons: Vue-based ecosystem — if not using Vue, Docusaurus might be easier
  • Get started with VitePress

Docsify

  • Tech: Pure HTML + JS
  • Use case: Super lightweight docs that load dynamically from Markdown files
  • Pros:
    • No build step
    • Simply include the Docsify script in an HTML page and it works
  • Cons: Client-side rendering only
  • Get started with Docsify

General Website Development Frameworks

Next.js

  • Tech: React + Node.js
  • Use case: Full-featured production websites (static or dynamic)
  • Pros:
    • SEO-friendly (SSR + SSG)
    • Integrated routing, API routes, image optimization
    • Large ecosystem, easy deployment on Vercel
  • Cons: Steeper learning curve
  • Get started with Next.js

Vite + React / Vue / Svelte

  • Tech: Any front-end framework
  • Use case: Lightweight dev setup for SPAs or landing pages
  • Pros:
    • Extremely fast dev server
    • Simple configuration, minimal boilerplate
  • Cons: No built-in backend or routing; you add manually
  • Get started with Vitejs

🎨 Template Libraries / UI Kits

For building beautiful designs fast:

Boilerplates & Templates

How You Could Try mkdocs

Clone the Repository

Clone the repository from cedricfyc/my-cv-blog

Create a Virtual Environment

  • If you do not have Python, downlaod and set-up from Python - Downloads

  • Go to the directory within the console

cd path-to-your-project
  • Create the virtual environment (I used Python 3.12+)
python -m venv env

Activate the Virtual Environment

Activate the virtual environment (it will contain the dependencies at the given versions).

  • For Windows:
venv\Scripts\activate
  • For Linux/macOS
source env/bin/activate

Install the Dependencies

Within the directory of the project, you will find a requirements.txt. Install the dependencies from it.

pip install -r requirements.txt

Adjust Some .md Files

Following the markdown syntax given at Markdown Cheatsheet, make the adjustments you want to visualise on given pages.

Serve the Website Locally

Serve to a port on your local network (it's safe).

mkdocs serve

http://127.0.0.1:8000/ is the default url, just follow it and if you set-up everything correctly, the website should now be hosted locally on your local network.

Experiment with the mkdocs.yml

Feel free to adjust the configurations within mkdocs.yml to personalise pages. All the documentation is listed in the resources section of this article.

My Goals With The Website

The website was originally inspired by me wanting to have a personal website and the fact that I am also working on some documentation work as part of my internship. I intend to present my cv, projects and blogs. I like adding new features to expand the possibilities within the website and wish to provide users with a great experience.

Resources

Subscribe to my newsletter

Powered by Buttondown