DevCodex

DevCodex is a private developer knowledge base built with MkDocs and the Material theme. It allows engineers to store technical notes in Markdown and browse them as a modern documentation website with navigation, search, diagrams, tags, and automatic linking between notes.

The repository only contains Markdown files, while MkDocs renders them into a documentation site.

---

Features

Fast navigation

Navigation is automatically generated from the folder structure using the awesome-pages plugin and .pages files.

Benefits:

• No large nav: configuration in mkdocs.yml
• Sidebar reflects the folder structure
• Order can be controlled with .pages

---

Full-text search

Search works across all documents and supports multiple languages.

Supported languages:

• English
• Turkish

Features:

• search suggestions
• highlighted results

---

Code block utilities

Code blocks include:

• syntax highlighting
• copy button
• improved text selection

Example:

echo "DevCodex"

---

Mermaid diagrams

Architecture diagrams can be written directly in Markdown.

Example:

flowchart LR
  A[Client] --> B[API]
  B --> C[(PostgreSQL)]
  B --> D[(Redis)]

Loading

---

Admonitions (information boxes)

Useful for warnings, notes, or tips.

Example:

!!! warning
    Kafka consumer rebalance may cause duplicate processing.

---

Backlinks

When one note links to another, the referenced note automatically shows a Backlinks section listing the notes that reference it.

Example link:

See also: [Outbox Pattern](../architecture/outbox-pattern.md)

---

Tags

Tags allow grouping notes by topic.

Example:

---
tags:
  - kafka
  - messaging
  - backend
---

All tags are automatically indexed on the Tags page.

docs/tags.md

# Tags

<!-- material/tags -->

This page displays all tags and links to notes that use them.

---

Automatic note listing (Macros)

The mkdocs-macros-plugin is used to automatically list notes in a folder.

Example usage in an index page:

docs/backend/index.md

# Backend

## Notes

{{ list_pages("backend") }}

This macro automatically lists all Markdown files in the folder.

Example output:

Kafka Consumer Groups
Spring Transaction Propagation
Virtual Threads

---

Repository Structure

Example structure:

DevCodex
│
├─ docs/
│   ├─ index.md
│   ├─ tags.md
│   │
│   ├─ backend/
│   │   ├─ index.md
│   │   ├─ kafka-consumer-groups.md
│   │   └─ .pages
│   │
│   ├─ architecture/
│   │   ├─ index.md
│   │   └─ .pages
│   │
│   ├─ devops/
│   │   └─ index.md
│   │
│   ├─ ai/
│   │   └─ index.md
│   │
│   └─ debug/
│       └─ index.md
│
├─ mkdocs.yml
├─ requirements.txt
├─ README.md
└─ .gitignore

All documentation content lives inside the docs/ directory.

---

Local Setup

1. Clone repository

git clone <repo-url>
cd DevCodex

---

2. Create virtual environment

python3 -m venv venv

Activate it.

Mac / Linux:

source venv/bin/activate

Windows:

venv\Scripts\activate

---

3. Install dependencies

pip install -r requirements.txt

---

4. Start documentation server

mkdocs serve

Open in browser:

http://127.0.0.1:8000

The server automatically reloads when Markdown files change.

---

Build Static Documentation

mkdocs build

Output directory:

site/

---

mkdocs.yml Configuration

Below is the active configuration with explanations.

site_name: DevCodex

theme:
  name: material
  features:
    - content.code.copy      # Adds copy button to code blocks
    - content.code.select    # Easier text selection inside code blocks
    - navigation.instant     # Instant page navigation without full reload
    - navigation.tracking    # Updates URL while scrolling through headings
    - navigation.top         # Adds "back to top" button
    - search.suggest         # Search suggestions while typing
    - search.highlight       # Highlights matching search results

markdown_extensions:
  - admonition               # Enables note/warning/tip blocks
  - toc:
      permalink: true        # Adds anchor links to headings
  - pymdownx.highlight:
      guess_lang: false      # Improves syntax highlighting behavior
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
                              # Enables Mermaid diagrams
  - pymdownx.inlinehilite    # Inline syntax highlighting
  - pymdownx.details         # Collapsible sections
  - pymdownx.snippets        # Include external code snippets
  - pymdownx.tabbed:
      alternate_style: true  # Tabbed content blocks

extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js
                              # Mermaid diagram library
  - javascripts/mermaid-init.js
                              # Custom Mermaid initialization

plugins:
  - search:
      lang: [en, tr]         # Multilingual search support
  - awesome-pages            # Automatic sidebar navigation using folders and .pages
  - backlinks_section:
      add_to_toc: false      # Do not include backlinks in table of contents
      hide_if_empty: true    # Hide backlinks section if empty
  - macros                   # Enables custom macros like list_pages()
  - tags                     # Enables tag system and tag index page

---

Writing Notes

Recommended structure:

# Title

## Problem
What problem does this solve?

## Context
When does this situation occur?

## Solution
How to solve the problem.

## Notes
Additional information.

---

Recommended Workflow

1. Start server

mkdocs serve

2. Create or edit Markdown files in docs/
3. Save the file
4. Browser reloads automatically

---

License

Private internal knowledge base.