Configure MkDocs infrastructure with Material theme and i18n support

.github/workflows/deploy-docs.yml

@@ -0,0 +1,62 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for git info
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  # Deploy job (only on main branch)
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -29,6 +29,9 @@ builds/
 build/
 *.egg-info
 
+# MkDocs generated site
+site/
+
 # translation object files
 *.pot
 *.mo

README.rst

@@ -96,6 +96,60 @@ installed, you can run builds manually:
     sphinx-build -b html -D language=en src _build/html/en
     sphinx-build -b html -D language=uk src _build/html/uk
 
+Building with MkDocs (New)
+===========================
+
+The project is being migrated to MkDocs with Material theme. MkDocs provides
+a modern documentation experience with Markdown authoring.
+
+Prerequisites
+-------------
+
+- Python 3.9 or higher (MkDocs setup is regularly tested on Python 3.11+)
+- `uv`_ (Python package manager)
+
+.. _uv: https://docs.astral.sh/uv/
+
+Local Development
+-----------------
+
+.. code-block:: shell
+
+    # Clone repository
+    git clone https://github.com/OpenRoost/pymastery-vp.git
+    cd pymastery-vp
+
+    # Install dependencies
+    uv sync
+
+    # Serve documentation locally (with live reload)
+    uv run mkdocs serve
+
+    # Open http://127.0.0.1:8000 in your browser
+
+Building for Production
+------------------------
+
+.. code-block:: shell
+
+    # Build static site
+    uv run mkdocs build
+
+    # Output will be in ./site/ directory
+
+Project Structure
+-----------------
+
+::
+
+    content/
+      en/           # English course content (Markdown)
+      uk/           # Ukrainian translations (in progress)
+      ru/           # Legacy Russian content (historical)
+    mkdocs.yml      # MkDocs configuration
+    pyproject.toml  # Project dependencies
+    src/            # Legacy Sphinx source (being phased out)
+
 Contributing to the project
 ===========================
 

content/en/index.md

@@ -0,0 +1,24 @@
+# Python for Web Developers
+
+Welcome to the Python for Web Developers course.
+
+## Course Overview
+
+This comprehensive course prepares complete beginners for junior/trainee developer positions
+by teaching Python, Django, and Django REST Framework.
+
+## Course Content
+
+_Content conversion from Sphinx/reStructuredText to Markdown is in progress (WP-243A)._
+
+Course materials are being migrated from the legacy Sphinx format to MkDocs.
+
+## About This Course
+
+This course is based on [original materials](https://github.com/PonomaryovVladyslav/PythonCourses)
+by Vladyslav Ponomaryov.
+
+---
+
+**Note:** This is a stub file created as part of the MkDocs infrastructure setup (WP-243B).
+Once WP-243A (content conversion) is complete, this will be replaced with the full course content.

content/uk/.translation-status.md

@@ -0,0 +1,25 @@
+# Ukrainian Translation Status
+
+This directory contains Ukrainian translations of the course content.
+
+## Current Status
+
+**Stub structure** - Translation is planned future work.
+
+The Ukrainian content structure has been created as part of WP-243B (MkDocs setup).
+Full translation from `content/en/` to `content/uk/` is planned as future work.
+
+## Contributing
+
+To contribute translations:
+1. Use `content/en/` as source
+2. Refer to legacy translations in `src/_locales/uk/` for terminology
+3. Follow the same directory structure as English content
+4. Submit pull requests with translated content
+
+## Translation Guidelines
+
+- Maintain technical term consistency
+- Keep code examples in English (with Ukrainian comments where helpful)
+- Preserve formatting and structure
+- Ensure links reference correct locale paths

content/uk/index.md

@@ -0,0 +1,12 @@
+# Python для веб-розробників
+
+Цей курс знаходиться в процесі перекладу українською мовою.
+
+## Зміст
+
+_Переклад в процесі. Зверніться до [англійської версії](../en/index.md)._
+
+---
+
+_Курс базується на [оригінальних матеріалах](https://github.com/PonomaryovVladyslav/PythonCourses) 
+від Владислава Пономарьова._

mkdocs.yml

@@ -0,0 +1,98 @@
+site_name: Python for Web Developers
+site_url: https://openroost.github.io/pymastery-vp/
+repo_url: https://github.com/OpenRoost/pymastery-vp
+repo_name: OpenRoost/pymastery-vp
+edit_uri: edit/main/content/
+
+docs_dir: content
+site_dir: site
+
+theme:
+  name: material
+  language: en
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.top
+    - navigation.tracking
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.code.annotate
+  palette:
+    # Light mode
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+plugins:
+  - search:
+      lang:
+        - en
+        - uk
+  - i18n:
+      docs_structure: folder
+      fallback_to_default: true
+      reconfigure_material: true
+      reconfigure_search: true
+      languages:
+        - locale: en
+          name: English
+          build: true
+          default: true
+        - locale: uk
+          name: Українська
+          build: true
+
+markdown_extensions:
+  # Admonitions
+  - admonition
+  - pymdownx.details
+
+  # Code blocks
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+
+  # Content features
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - attr_list
+  - md_in_html
+  - def_list
+
+  # Navigation
+  - toc:
+      permalink: true
+      toc_depth: 3
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/OpenRoost/pymastery-vp
+      name: GitHub Repository
+  generator: false  # Hide "Made with Material for MkDocs" footer
+
+copyright: >
+  Copyright © 2024-2026 OpenRoost. 
+  Derivative work based on 
+  <a href="https://github.com/PonomaryovVladyslav/PythonCourses">original course</a> 
+  by Vladyslav Ponomaryov.

pyproject.toml

@@ -43,6 +43,10 @@ dependencies = [
     "sphinx-copybutton>=0.5.2",
     "sphinx-reredirects>=0.1.3",
     "sphinxcontrib-svg2pdfconverter>=1.2.2",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.7.1",
+    "mkdocs-static-i18n>=1.3.0",
+    "pymdown-extensions>=10.20.1",
 ]
 
 [project.urls]