Tracking issue for docs unification (#112)

Author: BinaryMuse

.github/workflows/deploy.yml

@@ -1,31 +1,45 @@
 name: Deploy to GitHub Pages
 
 on:
-  # Trigger the workflow every time you push to the `main` branch
-  # Using a different branch name? Replace `main` with your branch’s name
   push:
-    branches: [ main ]
-  # Allows you to run this workflow manually from the Actions tab on GitHub.
+    branches: [main]
   workflow_dispatch:
 
-# Allow this job to clone the repo and create a page deployment
 permissions:
   contents: read
   pages: write
   id-token: write
 
+# Allow only one concurrent deployment
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout your repository using git
+      - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Install, build, and upload your site
-        uses: withastro/action@v4
-        # with:
-          # path: . # The root location of your Astro project inside the repository. (optional)
-          # node-version: 18 # The specific version of Node that should be used to build your site. Defaults to 18. (optional)
-          # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Build site
+        run: uv run mkdocs build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
 
   deploy:
     needs: build

.gitignore

@@ -1,16 +1,12 @@
 # build output
-dist/
-# generated types
-.astro/
+site/
 
-# dependencies
-node_modules/
-
-# logs
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-pnpm-debug.log*
+# Python / uv
+.venv/
+__pycache__/
+*.py[cod]
+.python-version
+uv.lock
 
 # environment variables
 .env
@@ -22,3 +18,6 @@ pnpm-debug.log*
 # swap vim files
 *.swp
 *.swo
+
+# multirepo temp directory
+temp_dir/

.vscode/extensions.json

@@ -1,12 +1,31 @@
 # Atuin docs
 
-This powers docs.atuin.sh
+This powers docs.atuin.sh - the unified documentation site for Atuin CLI and Atuin Desktop.
 
-You will find markdown files within src/content/docs
+This site uses [MkDocs](https://www.mkdocs.org/) with the [Material theme](https://squidfunk.github.io/mkdocs-material/) and the [mkdocs-multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin) to pull documentation from multiple repositories.
 
-Get started with
+## Documentation sources
 
+- **Atuin CLI**: Documentation lives in the [atuinsh/atuin](https://github.com/atuinsh/atuin) repository under `docs/`
+- **Atuin Desktop**: Documentation lives in the [atuinsh/desktop](https://github.com/atuinsh/desktop) repository under `docs/`
+
+## Local development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run local dev server
+uv run mkdocs serve
+
+# Build the site
+uv run mkdocs build
 ```
-npm install
-npm run dev
-```
+
+## Contributing
+
+To contribute to the documentation:
+
+- For Atuin CLI docs, submit PRs to [atuinsh/atuin](https://github.com/atuinsh/atuin)
+- For Atuin Desktop docs, submit PRs to [atuinsh/desktop](https://github.com/atuinsh/desktop)
+- For site-wide changes (navigation, theme, etc.), submit PRs to this repository

.vscode/launch.json

@@ -0,0 +1,15 @@
+# Atuin Documentation
+
+Welcome to the unified Atuin documentation.
+
+## Atuin CLI
+
+A magical shell history tool that replaces your existing shell history with a SQLite database, and records additional context for your commands. Sync your shell history between all of your machines - fully end-to-end encrypted.
+
+[Get started with Atuin CLI →](cli/)
+
+## Atuin Desktop
+
+Runbooks and automation for your terminal. Build, share, and run operational runbooks with a powerful block-based interface.
+
+[Get started with Atuin Desktop →](desktop/)

README.md

@@ -0,0 +1,8 @@
+/* Light/dark mode image switching */
+body[data-md-color-scheme="default"] .img-dark {
+  display: none !important;
+}
+
+body[data-md-color-scheme="slate"] .img-light {
+  display: none !important;
+}

astro.config.mjs

@@ -0,0 +1,98 @@
+site_name: Atuin Documentation
+site_url: https://docs.atuin.sh
+repo_url: https://github.com/atuinsh/atuin
+repo_name: atuinsh/atuin
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: deep purple
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: deep purple
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - content.action.edit
+    - content.action.view
+
+plugins:
+  - search
+  - multirepo:
+      cleanup: false
+  - git-revision-date-localized:
+      enable_creation_date: true
+  - redirects:
+      redirect_maps:
+        "guide/getting-started.md": "cli/guide/getting-started.md"
+        "guide/installation.md": "cli/guide/installation.md"
+        "guide/sync.md": "cli/guide/sync.md"
+        "guide/import.md": "cli/guide/import.md"
+        "guide/basic-usage.md": "cli/guide/basic-usage.md"
+        "guide/dotfiles.md": "cli/guide/dotfiles.md"
+        "guide/theming.md": "cli/guide/theming.md"
+        "configuration/config.md": "cli/configuration/config.md"
+        "configuration/key-binding.md": "cli/configuration/key-binding.md"
+        "reference/list.md": "cli/reference/list.md"
+        "reference/search.md": "cli/reference/search.md"
+        "reference/stats.md": "cli/reference/stats.md"
+        "reference/doctor.md": "cli/reference/doctor.md"
+        "reference/daemon.md": "cli/reference/daemon.md"
+        "reference/import.md": "cli/reference/import.md"
+        "reference/info.md": "cli/reference/info.md"
+        "reference/gen-completions.md": "cli/reference/gen-completions.md"
+        "reference/prune.md": "cli/reference/prune.md"
+        "reference/sync.md": "cli/reference/sync.md"
+        "self-hosting/server-setup.md": "cli/self-hosting/server-setup.md"
+        "self-hosting/usage.md": "cli/self-hosting/usage.md"
+        "self-hosting/docker.md": "cli/self-hosting/docker.md"
+        "self-hosting/kubernetes.md": "cli/self-hosting/kubernetes.md"
+        "self-hosting/systemd.md": "cli/self-hosting/systemd.md"
+        "known-issues.md": "cli/known-issues.md"
+        "integrations.md": "cli/integrations.md"
+        "faq.md": "cli/faq.md"
+        "uninstall.md": "cli/uninstall.md"
+        "sync-v2.md": "cli/sync-v2.md"
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - md_in_html
+  - tables
+  - pymdownx.keys
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+extra_css:
+  - stylesheets/extra.css
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/atuinsh/atuin
+    - icon: fontawesome/brands/discord
+      link: https://discord.gg/jR3tfchVvW
+
+nav:
+  - Home: index.md
+  - CLI: "!import https://github.com/atuinsh/atuin?branch=main&docs_dir=docs/docs/*&config=docs/mkdocs.yml"
+  - Desktop: "!import https://github.com/atuinsh/desktop?branch=main&docs_dir=docs/docs/*&config=docs/mkdocs.yml"