Split documentation into multiple pages

Author: ltmx

.github/workflows/docs.yml

@@ -46,10 +46,10 @@ jobs:
 
       - name: Stage API into docs tree
         run: |
-          rm -rf docs/api
-          mkdir -p docs/api
-          cp -r Documentation~/api/_site/* docs/api/
-          cp docs/api-stub/index.html docs/api/index.html
+          rm -rf docs~/api
+          mkdir -p docs~/api
+          cp -r Documentation~/api/_site/* docs~/api/
+          cp docs~/api-stub/index.html docs~/api/index.html
 
       - name: Install MkDocs
         run: pip install -r requirements-docs.txt
@@ -60,7 +60,7 @@ jobs:
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: site
+          path: site~
 
   deploy:
     needs: build

.github/workflows/main.yml

@@ -69,10 +69,11 @@ jobs:
             -x ".cursorignore" \
             -x "Tests/*" \
             -x "Documentation~/*" \
-            -x "docs/*" \
+            -x "docs~/*" \
+            -x "overrides~/*" \
             -x "mkdocs.yml" \
             -x "requirements-docs.txt" \
-            -x "site/*"
+            -x "site~/*"
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2

.gitignore

@@ -2,9 +2,12 @@
 !Documentation~/**/*.csproj
 *.csproj.meta
 
-# Documentation builds (Documentation~ trailing ~ = Unity ignores folder on import)
-site/
-docs/api/
+# Documentation builds (~ suffix = Unity ignores folder on import)
+site~/
+docs~/api/
+docs.meta
+overrides.meta
+site.meta
 Documentation~/api/
 Documentation~/**/*.meta
 Documentation~/**/bin/

Documentation~/README.md

@@ -2,6 +2,8 @@
 
 This folder is named **`Documentation~`** so Unity **ignores it entirely** when mathx is imported as a UPM package (trailing `~` is a Unity convention).
 
+The same applies to **`docs~`**, **`overrides~`**, and **`site~`** at the package root — MkDocs guides, theme overrides, and local build output.
+
 DocFX stubs use `Stubs/Unity.Stubs.stub` (not `.cs`). Never commit `bin/`, `obj/`, or `.dll` outputs — Unity loads them as plugins and conflicts with `Mathematics.Mathx.asmdef`.
 
 ## Prerequisites
@@ -19,18 +21,18 @@ dotnet tool install -g docfx   # once
 docfx metadata docfx.json
 docfx build docfx.json
 
-# Merge API into docs before MkDocs (included in site output)
-rm -rf docs/api
-mkdir -p docs/api
-cp -r Documentation~/api/_site/* docs/api/
-cp docs/api-stub/index.html docs/api/index.html
+# Merge API into docs~ before MkDocs (included in site~ output)
+rm -rf docs~/api
+mkdir -p docs~/api
+cp -r Documentation~/api/_site/* docs~/api/
+cp docs~/api-stub/index.html docs~/api/index.html
 
 # Guides (MkDocs Material)
 cd ..
 pip install -r requirements-docs.txt
 mkdocs build
 ```
 
-Open `site/index.html` locally, or run `mkdocs serve` for live reload (guides only until API is copied).
+Open `site~/index.html` locally, or run `mkdocs serve` for live reload (guides only until API is copied).
 
 Published site: [ltmx.github.io/Unity.mathx](https://ltmx.github.io/Unity.mathx/)

README.md

@@ -133,7 +133,7 @@ Topic guides: [fluent chains](https://ltmx.github.io/Unity.mathx/guides/fluent-c
 
 Edit Mode tests ship in `Tests/` (Unity Test Framework). Package tests require `"testables": ["com.ltmx.mathematics.mathx"]` in your **project** `Packages/manifest.json` (plus `com.unity.test-framework`). Then open **Window → General → Test Runner → Edit Mode**.
 
-See [docs/quality.md](docs/quality.md) or the [Quality page](https://ltmx.github.io/Unity.mathx/quality/) for setup, golden-value regeneration, and IL2CPP validation.
+See [docs~/QUALITY.md](docs~/QUALITY.md) or the [Quality page](https://ltmx.github.io/Unity.mathx/quality/) for setup, golden-value regeneration, and IL2CPP validation.
 
 <br>