Change to docfx website, move sa-mp docs to legacy, initial batch of open.mp docs

.github/workflows/deploy.yml

@@ -9,36 +9,50 @@ on:
       - main
 
 jobs:
-  build-and-deploy:
+  build:
     runs-on: ubuntu-latest
 
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
         with:
-          node-version: '18'
-          cache: 'npm'
+          dotnet-version: '10.x'
 
-      - name: Install dependencies
-        run: npm ci
+      - name: Install DocFX
+        run: dotnet tool install -g docfx
 
-      - name: Build docs
-        run: npm run docs:build
+      - name: Build Libraries
+        run: cd sampsharp-src && ./build.sh component
+
+      - name: Build documentation
+        run: docfx docfx.json
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: 'docs/.vitepress/dist'
+          path: '_site'
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev')
+    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
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -1,6 +1,4 @@
-node_modules/
-docs/.vitepress/dist/
-docs/.vitepress/cache/
-.DS_Store
-*.local
-.env.local
+_site/**
+
+api/**
+!api/index.md

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "sampsharp-src"]
+	path = sampsharp-src
+	url = https://github.com/ikkentim/sampsharp.git

.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Run open.mp gamemode",
+      "type": "dotnet",
+      "request": "launch",
+      "projectPath": "${workspaceFolder}/sampsharp-src/test/TestMode.OpenMp.Entities/TestMode.OpenMp.Entities.csproj"
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "chat.tools.terminal.autoApprove": {
+    "docfx": true,
+    "test": true
+  },
+  "cSpell.words": ["blockquotes", "frontmatter", "sampsharp", "textdraw"]
+}

.vscode/tasks.json

@@ -0,0 +1,13 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "docfx serve",
+      "type": "shell",
+      "command": "docfx",
+      "args": ["--serve"],
+      "isBackground": true,
+      "problemMatcher": []
+    }
+  ]
+}

404.md

@@ -0,0 +1,92 @@
+---
+title: Page Not Found
+_disableContribution: true
+_disableAfaf: true
+---
+
+<style>
+  .page-container {
+    max-width: 900px;
+    margin: 0 auto;
+    padding: 0 20px;
+    text-align: center;
+  }
+
+  .error-container {
+    padding: 60px 20px;
+  }
+
+  .error-code {
+    font-size: 120px;
+    font-weight: bold;
+    color: #0078d4;
+    margin: 0;
+    line-height: 1;
+  }
+
+  .error-message {
+    font-size: 28px;
+    color: var(--bs-body-color, #333);
+    margin: 20px 0;
+  }
+
+  .error-description {
+    font-size: 16px;
+    color: var(--bs-body-color, #666);
+    margin: 20px 0 40px 0;
+    opacity: 0.8;
+  }
+
+  .error-links {
+    display: flex;
+    gap: 20px;
+    justify-content: center;
+    flex-wrap: wrap;
+  }
+
+  .error-link {
+    display: inline-block;
+    padding: 12px 24px;
+    background-color: #0078d4;
+    color: white;
+    text-decoration: none;
+    border-radius: 6px;
+    transition: all 0.3s ease;
+  }
+
+  .error-link:hover {
+    background-color: #005a9e;
+    transform: translateY(-2px);
+  }
+
+  .error-link.secondary {
+    background-color: var(--bs-body-bg, #f3f3f3);
+    color: #0078d4;
+    border: 2px solid #0078d4;
+  }
+
+  .error-link.secondary:hover {
+    background-color: #0078d4;
+    color: white;
+  }
+</style>
+
+<div class="page-container">
+
+<div class="error-container">
+
+# <p class="error-code">404</p>
+
+<p class="error-message">Page Not Found</p>
+
+<p class="error-description">Sorry, we couldn't find the page you're looking for. It may have been moved or no longer exists.</p>
+
+<div class="error-links">
+  <a href="/" class="error-link">Back to Home</a>
+  <a href="/docs/" class="error-link secondary">Documentation</a>
+  <a href="/api/" class="error-link secondary">API Reference</a>
+</div>
+
+</div>
+
+</div>

AGENTS.md

@@ -0,0 +1,166 @@
+---
+title: DocFX Cross-Reference (xref) Guide
+---
+
+# DocFX Cross-Reference (xref) Guide
+
+This file summarizes all essential knowledge for writing correct cross-references (xrefs) in DocFX-based documentation, so you never make mistakes again.
+
+## 1. YAML Frontmatter and UID
+- Every conceptual Markdown file that should be referenced **must** have a unique `uid` in its YAML frontmatter:
+  ```yaml
+  ---
+  title: My Page Title
+  uid: my-unique-id
+  ---
+  ```
+- The `uid` must be unique within the documentation set.
+- If a file has no `uid`, it **cannot** be referenced via xref.
+- For API reference files, the UID is auto-generated from the API signature (e.g., `System.String`).
+
+## 2. Basic xref Syntax
+- To reference a UID from anywhere in your docs, use:
+  ```
+  <xref:my-unique-id>
+  ```
+- Or, for Markdown link text:
+  ```
+  [Link Text](xref:my-unique-id)
+  ```
+- This works for both conceptual docs and API docs.
+
+## 3. Best Practices
+- Always check that the target file has a `uid` in its YAML frontmatter.
+- Use short, descriptive UIDs (lowercase, hyphens/underscores if needed).
+- Never duplicate UIDs across files.
+- Prefer `xref:` links over relative links for conceptual docs when possible.
+- For API docs, use the full type/member name as UID (e.g., `System.String`, `MyNamespace.MyClass.MyMethod`).
+
+## 4. Troubleshooting
+- If an xref link does not resolve, check:
+  - The target file has a `uid`.
+  - The UID is spelled correctly.
+  - The UID is unique.
+- Use DocFX build output to spot unresolved xrefs.
+
+## 5. Example
+```markdown
+See [the events article](xref:events) for more details.
+```
+
+## 6. Useful Links
+- [DocFX Markdown Documentation](https://dotnet.github.io/docfx/docs/markdown.html)
+- [DocFX Links and Cross References](https://dotnet.github.io/docfx/docs/links-and-cross-references.html)
+
+---
+
+**Summary:**
+- Always use `uid` in YAML frontmatter for xref targets.
+- Use `xref:uid` syntax for cross-references.
+- Check for uniqueness and spelling.
+- Prefer xref over relative links for maintainability.
+
+---
+
+## 7. DocFX Markdown Features Cheat Sheet
+
+### Alerts
+Use blockquotes with special keywords for colored callouts:
+
+```
+> [!NOTE]
+> Information the user should notice even if skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Essential information required for user success.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+
+> [!WARNING]
+> Dangerous certain consequences of an action.
+```
+
+### Includes
+Reuse content from other markdown files:
+
+Inline include:
+```
+Text before [!INCLUDE [<title>](<filepath>)] and after.
+```
+Block include:
+```
+[!INCLUDE [my-block](../../includes/my-block.md)]
+```
+
+### Code Snippets
+Embed code from files, optionally with line/region selection and highlights:
+```
+[!code-csharp[](Program.cs)]
+[!code-csharp[](Program.cs#region)]
+[!code-csharp[](Program.cs#L12-L16)]
+[!code-csharp[](Program.cs?highlight=2,5-7,9-)]
+```
+
+### Tabs
+Create tabbed content for platform or language variants:
+```
+# [Linux](#tab/linux)
+Linux content...
+
+# [Windows](#tab/windows)
+Windows content...
+
+---
+```
+
+### Diagrams
+Embed diagrams using mermaid or PlantUML:
+
+**Mermaid:**
+````
+```mermaid
+flowchart LR
+  A --> B
+```
+````
+
+**PlantUML:**
+````
+```plantuml
+Bob -> Alice : hello
+```
+````
+
+### Math Expressions
+Use LaTeX math inline or as blocks (modern template only):
+
+Inline: `This is inline math: $\sqrt{3x-1}$`
+
+Block:
+```
+$$
+\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
+$$
+```
+
+### Images & Video
+Embed images:
+```
+![alt-text](image-link.png)
+```
+Embed video:
+```
+> [!Video https://www.youtube.com/embed/ID]
+```
+
+---
+
+**Summary:**
+- Always use `uid` in YAML frontmatter for xref targets.
+- Use `xref:uid` syntax for cross-references.
+- Prefer xref over relative links for maintainability.
+- Use DocFX Markdown features (alerts, includes, code snippets, tabs, diagrams, math, etc.) for rich documentation.