docs: reorganize documentation site and simplify README

Signed-off-by: Jemin Huh <[email protected]>

Author: JM-Lab

.github/workflows/docs-site.yml

@@ -0,0 +1,67 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "docs-overrides/**"
+      - "mkdocs.yml"
+      - "docs/requirements.txt"
+      - ".github/workflows/docs-site.yml"
+  push:
+    paths:
+      - "docs/**"
+      - "docs-overrides/**"
+      - "mkdocs.yml"
+      - "docs/requirements.txt"
+      - ".github/workflows/docs-site.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install docs dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy Docs
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    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,5 +1,6 @@
 HELP.md
 .DS_Store
+.venv/
 target/
 !.mvn/wrapper/maven-wrapper.jar
 !**/src/main/**/target/
@@ -47,3 +48,4 @@ vite.generated.ts
 !/electron/package-lock.json
 /src/main/bundles/
 /log
+site/

README.md

@@ -0,0 +1,20 @@
+{% extends "base.html" %}
+
+{% block extrahead %}
+  {{ super() }}
+  {% set page_title = page.title ~ " - " ~ config.site_name if page and page.title else config.site_name %}
+  {% set page_description = page.meta.description if page and page.meta and page.meta.description else config.site_description %}
+  {% set page_url = config.site_url ~ page.url if page and page.url else config.site_url %}
+  {% set social_image = config.site_url ~ "assets/images/icon.png" %}
+  <link rel="canonical" href="{{ page_url | e }}">
+  <meta property="og:site_name" content="{{ config.site_name | e }}">
+  <meta property="og:type" content="website">
+  <meta property="og:title" content="{{ page_title | e }}">
+  <meta property="og:description" content="{{ page_description | e }}">
+  <meta property="og:url" content="{{ page_url | e }}">
+  <meta property="og:image" content="{{ social_image | e }}">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="{{ page_title | e }}">
+  <meta name="twitter:description" content="{{ page_description | e }}">
+  <meta name="twitter:image" content="{{ social_image | e }}">
+{% endblock %}

docs-overrides/main.html

@@ -0,0 +1,5 @@
+# Images
+
+Place documentation screenshots and diagrams for MkDocs pages in this directory.
+
+The repository already contains demo images at the project root, but keeping documentation assets under `docs/assets/images/` makes MkDocs packaging simpler and more predictable.