Why I Chose MkDocs for the Blog

Building Finfluencers Trade is a journey, and I'm committed to documenting it openly – the technical challenges, research findings, and strategic pivots. This blog is central to that "Building in Public" approach.

Documenting this journey requires a blog that's easy to manage and integrates with my development workflow. After considering different options, I chose MkDocs with the Material theme because its focus on Markdown, static site generation, and developer experience perfectly matched my needs for the Finfluencers Trade blog.

The long-term plan for Finfluencers Trade includes a SaaS application, and this blog will be an integral part of it, driving content and SEO from day one. However, the SaaS tool itself doesn't exist yet. My immediate need was to start the blog to build authority and search presence, alongside a simple initial landing page.

This phased approach meant I needed a blog platform that could operate independently now but integrate seamlessly later. While platforms like Ghost CMS are excellent for integrated publishing, I needed a setup where the blog's content and structure remained stable even when the main site's front-end eventually switches from a simple landing page to the full SaaS application. A more coupled system felt less flexible for this specific transition.

This split simplified the requirements for the blog platform. I didn't need dynamic features or user management for the blog itself. I needed a tool that was excellent at one thing: turning Markdown files into a fast, clean, static website.

I'd seen MkDocs used for documentation sites and blogs by other developers and companies. Its simplicity and focus on Markdown appealed to me. Specifically, the Material for MkDocs theme caught my eye – it looked professional, had built-in blogging features, and was highly configurable.

So, I chose MkDocs with the Material theme.

Requirements Met

Here's why it fits:

1. Markdown-First: I write everything in Markdown. MkDocs uses these files directly. No database, no complex editor, just .md files in a Git repository.
2. Static Site Generation: It generates plain HTML, CSS, and JavaScript. This makes the blog fast and secure. While MkDocs sites can be hosted easily on platforms like GitHub Pages, I chose Vercel because I also need server-side functionality for features like the newsletter subscription, which Vercel handles seamlessly alongside the static blog content.
3. Developer Workflow: The entire site lives in Git. Content updates are just git push. This fits perfectly with how I already work.
4. Material Theme: This theme provides most of the features I need out-of-the-box: code highlighting, search, responsive design, and a dedicated blog plugin.
5. Configuration over Code (Mostly): Customizations are primarily handled through the mkdocs.yml configuration file, not by writing complex theme code.

My Setup Example

Getting started was direct:

1. Structure: I created a simple directory structure, including the requirements.txt file listing dependencies:

   finfluencers-trade/
   ├── docs/
   │   ├── blog/
   │   │   ├── posts/           # Blog post markdown files
   │   │   │   └── choosing-our-blog-framework-mkdocs.md
   │   │   ├── authors.yml      # Author definitions
   │   │   └── index.md         # Blog landing page
   │   ├── assets/
   │   │   └── images/        # Site images (like logo)
   │   ├── overrides/         # Theme customizations (CSS, HTML partials)
   │   ├── stylesheets/
   │   │   └── extra.css      # Custom CSS rules
   │   ├── index.md           # Site home page (distinct from blog index)
   │   └── mission.md         # Other static pages
   ├── mkdocs.yml             # Main configuration file
   └── requirements.txt       # Python dependencies
   

2. Installation: With Python and pip set up, installing MkDocs and all necessary plugins is done via the requirements file:

   pip install -r requirements.txt
   

3. Author Definition: The mkdocs-blog-plugin uses an authors.yml file (defined in mkdocs.yml) to manage author details for posts:

   # docs/blog/authors.yml
   authors:
     andreskull:
       name: Andres Kull
       description: Creator
       avatar: /assets/images/authors/andreskull-avatar.png
       url: https://twitter.com/andres_kull
   

   This allows adding author metadata easily to the frontmatter of each post.

4. Configuration (mkdocs.yml): This file controls everything. Key settings include linking the theme, plugins (like the blog plugin and authors file), navigation, and markdown extensions:

   # mkdocs.yml (snippet)
   site_name: Finfluencers.Trade
   site_author: Andres Kull
   site_url: https://finfluencers.trade
   site_description: Analytics and blog platform for financial influencers
   
   theme:
     name: material
     logo: assets/images/logo.png
     custom_dir: docs/overrides
     palette:
       scheme: slate # Force dark mode
   
   plugins:
     - blog:
         blog_dir: blog # Tells the plugin where blog posts live
         authors_file: blog/authors.yml # Points to author definitions
         post_url_format: "{date}/{slug}/" # Structure for post URLs
     - search
   
   markdown_extensions:
     # Standard markdown features + extras like pymdownx for code blocks
     - pymdownx.highlight
     - pymdownx.superfences
     - admonition
     - meta # For frontmatter
   
   nav: # Defines site navigation
     - Home: index.md
     - Our Mission: mission.md
     - Blog:
       - blog/index.md
   
   extra_css:
     - stylesheets/extra.css # Link custom styles
   

Straightforward and Effective

MkDocs isn't trying to be a full-blown CMS. It's a static site generator that excels at converting Markdown into websites. For my needs – a dedicated blog focused on content, integrated with a developer workflow – it's the right tool for the job. It lets me focus on writing and sharing the Finfluencers Trade journey.