Codelogium

Developer logs, notes, and learning paths — built with MkDocs Material.

Live site: codelogium.github.io

---

What Is This

A personal documentation site covering things I learn, debug, and build as a developer. Not a tutorial site — more of a second brain that happens to be public.

Sections include Java, Spring, Databases, Network, Lab (Git, Docker, CI/CD), and a Blog for stories and reflections.

---

Tech Stack

Tool	Purpose
MkDocs Material	Static site framework and theme
GitHub Pages	Hosting and deployment
GitHub Actions	CI/CD pipeline for auto-deploy on push
git-revision-date-localized	Shows creation and update dates on pages
git-committers	Shows contributor avatars on pages
mkdocs-categories-plugin	Auto-generates category pages from front matter
mkdocs-blogging-plugin	Blog index and pagination
Google Analytics (GA4)	Traffic and engagement tracking
Google Search Console	SEO and sitemap submission

---

Project Structure

codelogium.github.io/
├── docs/
│   ├── index.md              # Home page
│   ├── blog/
│   │   ├── index.md          # Blog overview
│   │   └── posts/            # Blog articles (managed by blog plugin)
│   ├── databases/            # Database articles
│   ├── java/                 # Java articles
│   ├── lab/
│   │   └── git/              # Git reference articles
│   ├── network/              # Network articles
│   ├── spring/               # Spring articles
│   ├── categories/           # Auto-generated category pages
│   ├── assets/               # Images and static files
│   ├── stylesheets/
│   │   └── extra.css         # Custom styles
│   └── javascript/
│       └── extra.js          # Custom JS (controls date/contributor visibility)
├── .github/
│   └── workflows/            # GitHub Actions deployment pipeline
├── mkdocs.yml                # MkDocs configuration
├── requirements.txt          # Python dependencies
└── README.md

---

Local Development

Prerequisites

• Python 3.x
• pip

Setup

# Clone the repo
git clone https://github.com/codelogium/codelogium.github.io.git
cd codelogium.github.io

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Run locally

python -m mkdocs serve

Site will be available at http://127.0.0.1:8000

Environment Variables

Variable	Purpose
MKDOCS_GIT_COMMITTERS_APIKEY	GitHub personal access token for the git-committers plugin. Prevents API rate limiting during local development. Needs public_repo scope.

Set it for your local session:

# Windows
set MKDOCS_GIT_COMMITTERS_APIKEY=your_token_here

# Mac/Linux
export MKDOCS_GIT_COMMITTERS_APIKEY=your_token_here

For the live deployment, this is set as a repository secret in GitHub Actions.

---

Deployment

Deployment is fully automated via GitHub Actions. Every push to main triggers a build and deploy to GitHub Pages.

The workflow file is at .github/workflows/. No manual deployment needed — just push and the site updates automatically.

---

Writing Content

Adding a new article

1. Create a .md file in the appropriate section folder (e.g. docs/java/my-article.md)
2. Add front matter:

---
title: "Your Article Title"
date: 2026-05-09
categories:
  - Java
description: "A short description for SEO and meta tags."
reading_time: 5
---

3. Add it to nav in mkdocs.yml
4. Commit and push

Adding a blog post

1. Create a .md file under docs/blog/posts/
2. Add front matter with at minimum title and date
3. Add <!-- more --> after the intro paragraph to set the excerpt shown on the blog index
4. Add authors: - alfahami if you have authors configured
5. Add it to nav in mkdocs.yml

Front matter reference

---
title: "Article Title"           # Page title and SEO title
date: 2026-05-09                  # Publication date (used by git plugin)
categories:                       # Auto-generates category pages
  - Git
  - Workflow
description: "SEO description"    # Used for meta description tag
reading_time: 5                   # Shown in blog-meta div (minutes)
---

---

Key Configuration Notes

git-revision-date-localized

- git-revision-date-localized:
    fallback_to_build_date: true
    type: timeago
    enable_creation_date: true
    enable_git_follow: true       # traces file history through renames
    exclude:
      - index.md
      - network/index.md
      - java/index.md
      - spring/index.md
      - databases/index.md
      - lab/index.md

• enable_git_follow: true preserves original creation dates when files are moved
• Section index pages are excluded to avoid showing incorrect dates on overview pages

Date and contributor visibility (extra.js)

Dates and contributor avatars are hidden by default via CSS and shown only on content pages via JavaScript. Overview/index pages don't show them. The logic is in docs/javascript/extra.js.

Categories

Categories are auto-generated from the categories: field in front matter by the mkdocs-categories-plugin. Add new category pages to the Categories nav section in mkdocs.yml when introducing a new category.

---

SEO Setup

• Google Analytics: GA4 property G-9L21ZFFY2J configured in mkdocs.yml
• Google Search Console: Site verified and sitemap submitted at sitemap.xml
• Sitemap: Auto-generated by MkDocs at https://codelogium.github.io/sitemap.xml
• Meta tags: title and description front matter fields are automatically injected as <meta> tags by MkDocs Material

---

Dependencies

All Python dependencies are listed in requirements.txt. Install with:

pip install -r requirements.txt

Current dependencies:

mkdocs-material
mkdocs-awesome-pages-plugin
mkdocs-blogging-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-git-committers-plugin-2
mkdocs-categories-plugin