docs: Move from mkdocs to quarto

.github/workflows/docs.yaml

@@ -38,7 +38,7 @@ jobs:
           poetry config virtualenvs.create false
           poetry install
 
-      - name: Generate documentation with changes from semantic-release
+      - name: Generate documentation
         run: makim --verbose docs.build
 
       - name: GitHub Pages action

.github/workflows/release.yaml

@@ -51,7 +51,7 @@ jobs:
           poetry config pypi-token.pypi ${PYPI_TOKEN}
           makim release.ci
 
-      - name: Generate documentation with changes from semantic-release
+      - name: Generate documentation
         if: ${{ github.event_name == 'workflow_dispatch' }}
         run: makim docs.build
 

.gitignore

@@ -101,6 +101,11 @@ ENV/
 
 # arx
 *.x.o
+/docs/api/
+/docs/_site/
+.quarto-tmp/
+.quarto-cache/
+.deno-cache/
 
 # llm
 .codex

.makim.yaml

@@ -362,12 +362,12 @@ groups:
       build:
         help: build documentation
         run: |
-          mkdocs build --config-file mkdocs.yaml
-          echo "arxlang.org" > ./build/CNAME
+          bash -lc 'mkdir -p .quarto-tmp .quarto-cache .deno-cache && rm -rf build && TMPDIR="$PWD/.quarto-tmp" XDG_CACHE_HOME="$PWD/.quarto-cache" DENO_DIR="$PWD/.deno-cache" quarto render docs && cp -a docs/_site build && echo "arxlang.org" > ./build/CNAME'
 
       preview:
         help: preview documentation page locally
-        run: mkdocs serve --watch docs --config-file mkdocs.yaml
+        run: |
+          bash -lc 'mkdir -p .quarto-tmp .quarto-cache .deno-cache && TMPDIR="$PWD/.quarto-tmp" XDG_CACHE_HOME="$PWD/.quarto-cache" DENO_DIR="$PWD/.deno-cache" quarto preview docs'
 
   release:
     vars:

AGENTS.md

@@ -33,7 +33,7 @@ Use this guidance for any change inside the Arx compiler repository:
   - `irx` for semantic analysis, lowering, and code generation
   - `astx` as the upstream node library consumed through IRx
   - `jsonschema` + `pyyaml` for Douki docstring validation
-- Docs stack: MkDocs + Material + mkdocstrings
+- Docs stack: Quarto
 
 ## Repository Layout
 
@@ -265,7 +265,7 @@ makim all.lint
 makim all.ci
 
 # docs
-mkdocs build --config-file mkdocs.yaml
+makim docs.build
 ```
 
 Codegen-focused checks:
@@ -304,7 +304,7 @@ When behavior changes, update docs in same PR:
 
 - language overview and getting-started examples
 - `docs/library/*` for syntax/placement rules
-- API docs are generated via mkdocstrings (`scripts/gen_ref_nav.py`)
+- API docs are generated for Quarto via `scripts/gen_api_docs.py`
 
 If embedding Arx docstrings inside Markdown code examples, prefer quadruple
 fences around the code block to safely include inner triple backticks.

docs/.gitignore

@@ -0,0 +1,2 @@
+/.quarto/
+**/*.quarto_ipynb

docs/_quarto.yml

@@ -0,0 +1,130 @@
+project:
+  type: website
+  output-dir: _site
+  pre-render:
+    - python ../scripts/gen_api_docs.py
+
+website:
+  title: ArxLang
+  site-url: https://arxlang.org
+  repo-url: https://github.com/arxlang/arx
+  favicon: favicon.ico
+  page-footer: "Copyright © 2022, ArxLang Team"
+  navbar:
+    logo: images/arx.png
+    right:
+      - icon: github
+        href: https://github.com/arxlang/arx
+      - text: Community
+        href: discord.md
+  sidebar:
+    style: docked
+    search: true
+    contents:
+      - text: Home
+        href: index.md
+      - text: Getting Started
+        href: getting-started.md
+      - section: Library
+        contents:
+          - text: Overview
+            href: library/index.md
+          - text: Modules
+            href: library/modules.md
+          - text: Functions
+            href: library/functions.md
+          - text: Classes
+            href: library/classes.md
+          - text: Data Types
+            href: library/datatypes.md
+          - text: Built-in Types
+            href: library/built-in-types.md
+          - text: Control Flow
+            href: library/control-flow.md
+          - text: Docstrings
+            href: library/docstrings.md
+      - section: ASTx
+        contents:
+          - text: Overview
+            href: astx/index.md
+          - text: Installation
+            href: astx/installation.md
+          - text: Conventions
+            href: astx/conventions.md
+          - text: Contributing
+            href: astx/contributing.md
+          - section: Tutorials
+            contents:
+              - text: Getting Started
+                href: astx/tutorials/get-started.ipynb
+              - text: Literals
+                href: astx/tutorials/literals.ipynb
+              - text: Variables
+                href: astx/tutorials/variables.ipynb
+              - text: Functions
+                href: astx/tutorials/functions.ipynb
+              - text: For Loops
+                href: astx/tutorials/for-loop.ipynb
+              - text: Context
+                href: astx/tutorials/context.ipynb
+              - text: Fibonacci
+                href: astx/tutorials/fibonacci.ipynb
+          - text: Historical Changelog
+            href: astx/changelog.md
+      - section: IRx
+        contents:
+          - text: Overview
+            href: irx/index.md
+          - text: Installation
+            href: irx/installation.md
+          - text: Architecture
+            href: irx/architecture.md
+          - text: Semantic Contract
+            href: irx/semantic-contract.md
+          - text: Runtime Features
+            href: irx/runtime-features.md
+          - text: Buffer View Model
+            href: irx/buffer-view-model.md
+          - text: Class Model
+            href: irx/class-model.md
+          - text: Contributing
+            href: irx/contributing.md
+          - section: Tutorials
+            contents:
+              - text: Getting Started
+                href: irx/tutorials/get-started.ipynb
+          - text: Historical Changelog
+            href: irx/changelog.md
+      - text: API Docs
+        href: api/index.md
+      - text: Syntax
+        href: syntax.md
+      - text: Roadmap
+        href: roadmap.md
+      - text: Contributing Guide
+        href: contributing.md
+      - text: Sponsor
+        href: sponsor.md
+      - text: Partners
+        href: partners.md
+      - text: Code of Conduct
+        href: coc.md
+      - text: Community
+        href: discord.md
+      - text: Governance
+        href: governance.md
+      - text: Changelog
+        href: changelog.md
+
+format:
+  html:
+    theme:
+      light: cosmo
+      dark: darkly
+    toc: true
+    code-copy: true
+    code-overflow: wrap
+    link-external-newwindow: true
+
+execute:
+  enabled: false