docs: adopted shadcn theme, added pages CI/CD, and tighten docs layout

Author: rudraditya21

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Docs CI/CD
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Configure Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-docs.txt
+
+      - name: Build docs (strict)
+        env:
+          SITE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    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

@@ -1,3 +1,4 @@
 site/
 .DS_Store
 __pycache__/
+.venv/

README.md

@@ -51,7 +51,10 @@ Every production script must include:
 Local docs workflow:
 
 ```bash
-python3 -m pip install mkdocs mkdocs-material
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+python3 -m pip install -r requirements-docs.txt
 mkdocs serve
 mkdocs build --strict
 ```

docs/stylesheets/extra.css

@@ -0,0 +1,23 @@
+/* Reduce excessive vertical spacing in article content. */
+article .typography h2 {
+  margin-top: 1.5rem;
+  margin-bottom: 0.5rem;
+}
+
+article .typography h3 {
+  margin-top: 1.1rem;
+  margin-bottom: 0.4rem;
+}
+
+article .typography p,
+article .typography ul,
+article .typography ol,
+article .typography pre,
+article .typography table,
+article .typography blockquote {
+  margin-top: 0.6rem;
+}
+
+article .typography li + li {
+  margin-top: 0.2rem;
+}

mkdocs.yml

@@ -1,18 +1,24 @@
 site_name: DevOps Scripts Library
 site_description: Industry-grade automation scripts for cloud, platform, CI/CD, databases, security, and SRE.
-site_url: https://github.com/rudraditya21/devops.scripts
+site_url: !ENV [SITE_URL, "http://127.0.0.1:8000/"]
+repo_url: https://github.com/rudraditya21/devops.scripts
 repo_name: devops.scripts
 docs_dir: docs
 site_dir: site
 strict: true
 
 theme:
-  name: mkdocs
-  language: en
+  name: shadcn
+  show_title: true
+  show_stargazers: true
+  pygments_style: github-dark
 
 plugins:
   - search
 
+extra_css:
+  - stylesheets/extra.css
+
 markdown_extensions:
   - admonition
   - attr_list
@@ -21,7 +27,7 @@ markdown_extensions:
   - md_in_html
   - tables
   - toc:
-      permalink: true
+      permalink: false
 
 nav:
   - Home: index.md

requirements-docs.txt

@@ -0,0 +1,2 @@
+mkdocs>=1.6,<2.0
+mkdocs-shadcn>=0.9,<1.0