Migrate from Sphinx to MkDocs: convert RST to MD, update config and scripts

Author: kukgini

.github/workflows/build-and-deploy.yml

@@ -35,13 +35,6 @@ jobs:
           python-version: '3.12'  # Specify exact version for reproducibility
           cache: 'pip'
 
-      - name: Cache Sphinx doctrees
-        uses: actions/cache@v4
-        with:
-          path: docs/.doctrees
-          key: sphinx-doctrees-${{ hashFiles('src/**') }}
-          restore-keys: |
-            sphinx-doctrees-
 
       - name: Install dependencies
         run: |
@@ -50,8 +43,8 @@ jobs:
       
       - name: Build HTML documentation
         run: |
-          echo "🔨 Building Sphinx documentation..."
-          sphinx-build -b html -d docs/.doctrees src docs
+          echo "🔨 Building MkDocs documentation..."
+          mkdocs build
           touch docs/.nojekyll
           echo "✅ Build completed!"
       

README.md

@@ -1,33 +1,27 @@
-# my-sphinx
+# Knowledge Utility Kit
 
-A project for publishing documentation to GitHub Pages using Sphinx.
+A project for publishing documentation to GitHub Pages using **MkDocs** and **Material for MkDocs**.
 
 ## 📁 Project Structure
 
 ```
-my-sphinx/
+kukgini.github.io/
 ├── .github/
 │   └── workflows/
 │       └── build-and-deploy.yml  # GitHub Actions automated build
 ├── bin/                    # Build tools (for local use)
 │   ├── build              # Build documentation
 │   ├── deploy             # Build + Git deployment
 │   └── clean              # Clean build artifacts
-├── src/                    # Documentation source files
-│   ├── bosh/
-│   ├── cf/
-│   ├── git/
-│   ├── golang/
-│   ├── os/
-│   ├── md/
-│   ├── z-diagrams/
-│   ├── conf.py            # Sphinx configuration
-│   └── index.rst          # Documentation main page
+├── src/                    # Documentation source files (Markdown)
+│   ├── ap2/
+│   ├── dt/
+│   ├── paas/
+│   ├── iaas/
+│   ├── _static/           # Custom CSS
+│   └── index.md           # Home page
 ├── docs/                   # Build output (for GitHub Pages deployment)
-│   ├── .nojekyll          # Disable Jekyll for GitHub Pages
-│   ├── index.html         # Main HTML page
-│   ├── _static/           # Static files (CSS, JS, etc.)
-│   └── ...                # Other HTML files
+├── mkdocs.yml              # MkDocs configuration
 ├── requirements.txt        # Python dependencies
 └── README.md
 ```
@@ -36,16 +30,12 @@ my-sphinx/
 
 ### 🤖 Automated Build (GitHub Actions)
 
-When you modify and commit source files in the `src/` directory, GitHub Actions will automatically build and deploy the documentation.
+When you modify and push source files, GitHub Actions will automatically build and deploy the documentation.
 
 **Trigger conditions:**
 - Changes to files in the `src/` directory
 - Changes to `requirements.txt`
-- Push to `master` or `main` branch
-
-**GitHub Actions execution status:**
-- Check execution status in the repository's **Actions** tab
-- After build completion, the `docs/` directory is automatically updated
+- Push to `main` branch
 
 ### 📦 Local Build
 
@@ -61,9 +51,9 @@ When you modify and commit source files in the `src/` directory, GitHub Actions
 
 **Process:**
 1. Create an isolated virtual environment (`.venv`)
-2. Install dependencies (`sphinx`, `sphinx_rtd_theme`, `recommonmark`)
-3. Build HTML documentation with Sphinx (`src/` → `docs/`)
-4. Create `.nojekyll` file (for GitHub Pages)
+2. Install dependencies (`mkdocs`, `mkdocs-material`)
+3. Build documentation (`src/` → `docs/`)
+4. Create `.nojekyll` file
 5. Automatically clean up virtual environment
 
 Build output is generated in the `docs/` directory.
@@ -80,123 +70,50 @@ Build output is generated in the `docs/` directory.
 3. Automatic commit
 4. Push to GitHub
 
-> **💡 Tip**: With GitHub Actions, you only need to modify sources and push without building locally!
-
 #### 3. Clean Build Artifacts
 
 ```bash
 ./bin/clean
 ```
 
-Deletes the `docs/`, `_build/`, and `.venv/` directories.
+Deletes the `docs/`, `site/`, and `.venv/` directories.
 
 ## 📝 Writing Documentation
 
 ### Adding Documents
 
-1. Create a `.rst` or `.md` file in the `src/` directory
-2. Add the new document to `src/index.rst`:
-
-```rst
-.. toctree::
-   :maxdepth: 1
-
-   your-new-document.md
-```
-
-3. Build and deploy:
-
-```bash
-./bin/deploy
-```
-
-### Supported Formats
-
-- **reStructuredText** (`.rst`): Sphinx default format
-- **Markdown** (`.md`): Supported through the `recommonmark` extension
-
-## 🌐 GitHub Pages Setup
-
-### 1. Enable GitHub Pages
-
-1. GitHub repository → **Settings** → **Pages**
-2. **Source**: Deploy from a branch
-3. **Branch**: `master` (or `main`)
-4. **Folder**: Select `/docs`
-5. **Save**
-
-### 2. GitHub Actions Permissions (Important!)
-
-1. GitHub repository → **Settings** → **Actions** → **General**
-2. In the **Workflow permissions** section:
-   - Select **Read and write permissions**
-   - Check **Allow GitHub Actions to create and approve pull requests**
-3. **Save**
-
-Without this setting, GitHub Actions cannot commit build results.
-
-### 3. Verify Automated Deployment
+1. Create a `.md` file in the `src/` directory.
+2. Add the new document to `mkdocs.yml` under `nav`:
 
-Now when you modify and push files in the `src/` directory:
-
-1. **GitHub Actions** automatically executes the build
-2. Build results are committed to `docs/`
-3. **GitHub Pages** automatically updates
-
-**Check execution:**
-- Check workflow execution status in the repository's **Actions** tab
-- When complete, the GitHub Pages site automatically updates
-
-## 🛠️ Advanced Usage
-
-### Manual Python Execution
-
-```bash
-# Build
-python3 bin/build
-
-# Deploy
-python3 bin/deploy
-
-# Clean
-python3 bin/clean
+```yaml
+nav:
+  - Home: index.md
+  - My Section:
+    - my-new-doc.md
 ```
 
-### Complete Rebuild
-
-```bash
-./bin/clean
-./bin/build
-```
-
-### Changing Sphinx Configuration
-
-You can change Sphinx settings by editing the `src/conf.py` file:
-
-- Change theme
-- Add extensions
-- Modify project metadata
-
-## 📦 Dependencies
-
-The project uses the following Python packages:
-
-- **sphinx**: Documentation generation tool
-- **sphinx_rtd_theme**: Read the Docs theme
-- **recommonmark**: Markdown support
+3. Build and deploy.
 
-Dependencies are automatically installed in an isolated virtual environment during build, so they don't affect your system Python environment.
+### Supported Features
 
-## 🔒 Isolated Build Environment
+- **Markdown**: Standard Markdown syntax.
+- **Admonitions**: `!!! note "Title"` blocks.
+- **Code Highlighting**: Fenced code blocks with language specifiers.
+- **Mermaid Diagrams**:
+  ```mermaid
+  graph TD
+    A[Start] --> B{Is it working?}
+    B -- Yes --> C[Great!]
+    B -- No --> D[Debug]
+  ```
 
-All builds run in a temporary virtual environment:
+## 🛠️ Configuration
 
-1. Create `.venv` when build starts
-2. Install dependencies
-3. Build documentation
-4. Automatically delete `.venv` after build completes
+You can change site settings by editing `mkdocs.yml`:
 
-You can use all necessary build tools while keeping your system Python environment clean.
+- Change theme colors
+- Add plugins
+- Modify navigation structure
 
 ## 📄 License
 

bin/build

@@ -24,11 +24,11 @@ def main():
     if sys.platform == "win32":
         venv_python = venv_dir / "Scripts" / "python.exe"
         venv_pip = venv_dir / "Scripts" / "pip.exe"
-        venv_sphinx = venv_dir / "Scripts" / "sphinx-build.exe"
+        venv_mkdocs = venv_dir / "Scripts" / "mkdocs.exe"
     else:
         venv_python = venv_dir / "bin" / "python"
         venv_pip = venv_dir / "bin" / "pip"
-        venv_sphinx = venv_dir / "bin" / "sphinx-build"
+        venv_mkdocs = venv_dir / "bin" / "mkdocs"
 
     try:
         # Step 1: Create virtual environment
@@ -42,10 +42,8 @@ def main():
         # Step 3: Build documentation
         print("\n🔨 Building documentation...")
         run_command([
-            str(venv_sphinx),
-            "-b", "html",
-            "src",
-            "docs"
+            str(venv_mkdocs),
+            "build"
         ], cwd=project_root)
 
         # Step 4: Create .nojekyll file for GitHub Pages

mkdocs.yml

@@ -0,0 +1,50 @@
+site_name: Knowledge Utility Kit
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+docs_dir: src
+site_dir: docs
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - tables
+  - attr_list
+
+extra_css:
+  - _static/custom.css
+
+nav:
+  - Home: index.md
+  - Agentic Commerce:
+    - ap2/ap2-samples.md
+  - Digital Credential:
+    - dt/ssi.md
+    - dt/askar_multitenancy_encryption_ko.md
+    - dt/askar_rekey_ko.md

requirements.txt

@@ -1,6 +1,2 @@
-sphinx>=7.0.0
-sphinx_rtd_theme
-sphinx-material>=0.0.36
-myst-parser>=2.0.0
-sphinx-book-theme>=1.0.0
-sphinxcontrib-mermaid>=0.9.0
+mkdocs>=1.5.0
+mkdocs-material>=9.4.0