python3 -m venv .venv
source .venv/bin/activate
pip install mkdocs mkdocs-material

my-docs/
├── docs/
│   ├── index.md
│   └── getting-started.md
├── mkdocs.yml
└── requirements.txt

site_name: My Platform Docs
site_url: https://docs.example.com
repo_url: https://github.com/org/my-docs
edit_uri: edit/main/docs/

theme:
  name: material
  language: fa
  features:
    - navigation.tabs
    - navigation.sections
    - search.suggest
    - content.code.copy
  palette:
    - scheme: default
      primary: indigo
      toggle:
        icon: material/brightness-4
        name: Dark mode
    - scheme: slate
      primary: indigo
      toggle:
        icon: material/brightness-7
        name: Light mode

plugins:
  - search

nav:
  - Home: index.md
  - شروع: getting-started.md

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - toc:
      permalink: true

mkdocs serve        # http://127.0.0.1:8000
mkdocs build        # خروجی در site/

mkdocs>=1.6
mkdocs-material>=9.5

platform-monorepo/
├── mkdocs.yml                 # root — portal اصلی
├── docs/
│   └── index.md
├── services/
│   ├── api/
│   │   ├── mkdocs.yml
│   │   └── docs/
│   │       └── index.md
│   └── worker/
│       ├── mkdocs.yml
│       └── docs/
│           └── index.md
└── requirements.txt

site_name: Platform Documentation
theme:
  name: material

plugins:
  - monorepo

nav:
  - Home: 'index.md'
  - API Service: '!include services/api/mkdocs.yml'
  - Worker Service: '!include services/worker/mkdocs.yml'

site_name: API Service
nav:
  - Overview: 'index.md'
  - Authentication: 'auth.md'
  - Endpoints: 'endpoints.md'

cd services/api && mkdocs serve   # فقط API docs
cd ../../ && mkdocs serve         # کل portal

site_name: Company Docs Portal
theme:
  name: material

plugins:
  - multirepo

nav:
  - Home: index.md
  - Imported Repos:
      - Backend API: '!import https://github.com/org/backend-api?branch=main&docs_dir=docs/*'
      - Frontend App: '!import https://github.com/org/frontend-app?branch=main&docs_dir=docs/*'
      - Infra: '!import https://github.com/org/infra?branch=main&docs_dir=docs/*'

nav:
  - Home: index.md
  - Platform:
      - Architecture: platform/architecture.md
      - Security: platform/security.md
  - Services:
      - API: services/api.md
      - Worker: services/worker.md
  - Runbooks:
      - Incident Response: runbooks/incident.md
      - Deploy: runbooks/deploy.md

pip install mike
mike deploy 1.0 latest --update-alias
mike set-default latest

extra:
  version:
    provider: mike

name: Build and Deploy MkDocs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'requirements.txt'
      - 'services/**/docs/**'
      - 'services/**/mkdocs.yml'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip
          cache-dependency-path: requirements.txt

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Build MkDocs
        env:
          # فقط اگر multirepo-plugin و repo خصوصی دارید:
          GithubAccessToken: ${{ secrets.DOCS_REPO_TOKEN }}
        run: mkdocs build --strict

      - uses: actions/configure-pages@v4

      - uses: actions/upload-pages-artifact@v3
        with:
          path: site/

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

stages:
  - build
  - deploy

variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
  paths:
    - .cache/pip

build-docs:
  stage: build
  image: python:3.12-slim
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - docs/**/*
        - mkdocs.yml
        - requirements.txt
        - services/**/docs/**/*
        - services/**/mkdocs.yml
  script:
    - pip install -r requirements.txt
    - mkdocs build --strict
  artifacts:
    paths:
      - site/
    expire_in: 1 day

deploy-docs:
  stage: deploy
  image: alpine:latest
  needs: [build-docs]
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
      changes:
        - docs/**/*
        - mkdocs.yml
        - requirements.txt
  before_script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
    - ssh-keyscan -p 667 docs-server.example.com >> ~/.ssh/known_hosts
  script:
    - rsync -avz --delete -e "ssh -p 667" site/ [email protected]:/var/www/docs/
  environment:
    name: production
    url: https://docs.example.com

      - name: Build MkDocs (multirepo)
        env:
          GithubAccessToken: ${{ secrets.DOCS_REPO_TOKEN }}
        run: mkdocs build --strict

mkdocs>=1.6.0
mkdocs-material>=9.5.0
mkdocs-monorepo-plugin>=1.1.0
mkdocs-multirepo-plugin>=0.8.0
mike>=2.0.0

┌─────────────────────────────────────────────────────────┐
│  Developer writes Markdown next to code                 │
│  services/api/docs/  +  services/api/mkdocs.yml         │
└────────────────────────┬────────────────────────────────┘
                         │ git push
                         ▼
┌─────────────────────────────────────────────────────────┐
│  CI: path filter → pip install → mkdocs build --strict  │
└────────────────────────┬────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
   GitHub Pages    nginx/rsync    S3 + CloudFront

# job جدا — فقط artifact، بدون deploy
preview-docs:
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - pip install -r requirements.txt
    - mkdocs build
  artifacts:
    paths: [site/]

theme:
  name: material
  language: fa
  direction: rtl

pip install mkdocs mkdocs-material mkdocs-monorepo-plugin
mkdocs new my-platform-docs
# mkdocs.yml را تنظیم کنید
# .github/workflows/docs.yml را اضافه کنید
git push