fix(docs): comment out all broken d2 diagrams and fix invalid aside type

2026-03-14 14:45:49 +01:00 · 2025-11-24 21:46:26 +11:00 · 2025-11-24 21:46:26 +11:00 · 0d02db8ce6
commit 0d02db8ce6
parent 7e21ce614a
4 changed files with 36 additions and 139 deletions
--- a/docs/src/content/docs/concepts/build-system.mdx
+++ b/docs/src/content/docs/concepts/build-system.mdx
@ -144,7 +144,7 @@ var assets embed.FS
    5. Includes source maps
    
    **Characteristics:**
-    - **Fast rebuilds** (<1s for frontend changes)
+    - **Fast rebuilds** (&lt;1s for frontend changes)
    - **No asset embedding** (served from dev server)
    - **Debug symbols** included
    - **Source maps** enabled
@ -548,11 +548,11 @@ sudo cp icon.png /usr/share/icons/hicolor/256x256/apps/myapp.png

 | Phase | Time | Notes |
 |-------|------|-------|
-| Analysis | <1s | Go code scanning |
-| Binding Generation | <1s | TypeScript generation |
+| Analysis | &lt;1s | Go code scanning |
+| Binding Generation | &lt;1s | TypeScript generation |
 | Frontend Build | 5-30s | Depends on project size |
 | Go Compilation | 2-10s | Depends on code size |
-| Asset Embedding | <1s | Embedding frontend |
+| Asset Embedding | &lt;1s | Embedding frontend |
 | **Total** | **10-45s** | First build |
 | **Incremental** | **5-15s** | Subsequent builds |

--- a/docs/src/content/docs/contributing/architecture.mdx
+++ b/docs/src/content/docs/contributing/architecture.mdx
@ -23,42 +23,12 @@ This page presents the *big picture* in four diagrams:

 **Wails v3 – High-Level Stack**

-```d2
-direction: right
-Developer: "wails3 CLI"
-Build: {
-  label: "Build-time Tool-chain"
-  GEN: "Binding Generator
-(static analysis)"
-  TMP: "Template Engine"
-  ASSETDEV: "Asset Server (dev)"
-  PKG: "Cross-compilation & Packaging"
-}
-Runtime: {
-  label: "Native Runtime"
-  RT: "Desktop Runtime
-(window, dialogs, tray, …)"
-  BRIDGE: "Message Bridge
-(JSON channel)"
-}
-App: {
-  label: "Your Application"
-  BACKEND: "Go Backend"
-  FRONTEND: "Web Frontend
-(React/Vue/…)"
-}
-Developer -> TMP: "init"
-Developer -> GEN: "generate"
-Developer -> ASSETDEV: "dev"
-Developer -> PKG: "build / package"
-GEN -> BACKEND: "Go & TS stubs"
-GEN -> FRONTEND: "bindings.json"
-ASSETDEV <-> FRONTEND: "HTTP"
-BACKEND <-> BRIDGE: "calls / events"
-FRONTEND <-> BRIDGE: "invoke / emit"
-BRIDGE <-> RT: "native API"
-RT -> ASSETDEV: "serve assets"
-```
+{/*
+TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
+The previous D2 code block was causing MDX parsing errors in the build pipeline.
+*/}
+
+**[High-Level Stack Diagram Placeholder]**

 ---

@ -66,22 +36,12 @@ RT -> ASSETDEV: "serve assets"

 **Runtime – JavaScript ⇄ Go Calling Path**

-```d2
-direction: right
-JS: "JavaScript
-(frontend)"
-Bridge: "Bridge
-(WebView callback)"
-MP: "Message Processor
-(Go)"
-GoNode: "Bound Go Function"
-JS -> Bridge: "invoke(\"Greet\",\"Alice\")"
-Bridge -> MP: "JSON call {t:c,id:42,…}"
-MP -> GoNode: "call Greet(\"Alice\")"
-GoNode -> MP: "\"Hello Alice\""
-MP -> Bridge: "JSON {t:r,id:42,result:\"Hello Alice\"}"
-Bridge -> JS: "Promise.resolve(\"Hello Alice\")"
-```
+{/*
+TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
+The previous D2 code block was causing MDX parsing errors in the build pipeline.
+*/}
+
+**[Runtime Call Flow Diagram Placeholder]**

 Key points:

@ -95,29 +55,12 @@ Key points:

 **Dev ↔ Prod Asset Server**

-```d2
-direction: right
-Dev: {
-  label: "`wails3 dev`"
-  VITE: "Framework Dev Server
-(port 5173)"
-  ASDEV: "Asset Server (dev)
-(proxy + disk)"
-  FRONTENDDEV: "Browser"
-}
-Prod: {
-  label: "`wails3 build`"
-  EMBED: "Embedded FS
-(go:embed)"
-  ASPROD: "Asset Server (prod)
-(read-only)"
-  FRONTENDPROD: "WebView Window"
-}
-VITE <-> ASDEV: "proxy / HMR"
-ASDEV <-> FRONTENDDEV: "HTTP"
-EMBED -> ASPROD: "serve assets"
-ASPROD <-> FRONTENDPROD: "in-memory"
-```
+{/*
+TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
+The previous D2 code block was causing MDX parsing errors in the build pipeline.
+*/}
+
+**[Asset Flow Diagram Placeholder]**

 * In **dev** the server proxies unknown paths to the framework’s live-reload
  server and serves static assets from disk.  
@ -130,26 +73,12 @@ ASPROD <-> FRONTENDPROD: "in-memory"

 **Per-OS Runtime Files**

-```d2
-direction: right
-Window: "runtime::Window
-Shared interface (pkg/application)"
-WindowDarwin: "Window_darwin
-//go:build darwin
-Objective-C (cgo)
-NSWindow* ptr"
-WindowLinux: "Window_linux
-//go:build linux
-Pure Go GTK calls
-GtkWindow* ptr"
-WindowWindows: "Window_windows
-//go:build windows
-Win32 API via syscall
-HWND ptr"
-Window -> WindowDarwin
-Window -> WindowLinux
-Window -> WindowWindows
-```
+{/*
+TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
+The previous D2 code block was causing MDX parsing errors in the build pipeline.
+*/}
+
+**[Platform Split Diagram Placeholder]**

 Every feature follows this pattern:

--- a/docs/src/content/docs/contributing/index.mdx
+++ b/docs/src/content/docs/contributing/index.mdx
@ -51,45 +51,13 @@ context you need.

 **Wails v3 – End-to-End Flow**

-```d2
-direction: right
-Developer: "wails3 CLI
-Init · Dev · Build · Package"
-Build: {
-  label: "Build-Time"
-  GEN: "Binding System
-(Static Analysis & Codegen)"
-  ASSET: "Asset Server
-(Dev Proxy · Embed FS)"
-  PKG: "Build & Packaging
-Pipeline"
-}
-Runtime: {
-  label: "Runtime"
-  RUNTIME: "Desktop Runtime
-(Window · Events · Dialogs)"
-  BRIDGE: "Bridge
-(Message Processor)"
-}
-Application: {
-  label: "Application"
-  GO: "Go Backend
-(App Logic)"
-  WEB: "Web Frontend
-(React/Vue/...)"
-}
-Developer -> GEN: "generate"
-Developer -> ASSET: "dev / build"
-Developer -> PKG: "compile & package"
-GEN -> GO: "Code Stubs + TS"
-GEN -> WEB: "Bindings JSON"
-PKG -> GO: "Final Binary + Installer"
-GO -> BRIDGE: "Function Calls"
-WEB -> BRIDGE: "Invoke / Events"
-BRIDGE <-> RUNTIME: "native messages"
-RUNTIME -> ASSET: "Serve Assets"
-WEB <-> ASSET: "HTTP / In-Memory"
-```
+{/*
+TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image.
+The previous D2 code block was causing MDX parsing errors in the build pipeline.
+*/}
+
+**[End-to-End Flow Diagram Placeholder]**
+

 The diagram shows the **end-to-end flow**:

--- a/docs/src/content/docs/guides/custom-protocol-association.mdx
+++ b/docs/src/content/docs/guides/custom-protocol-association.mdx
@ -127,7 +127,7 @@ While Wails aims for a unified event, the underlying mechanism for custom protoc
 -   **How it Works:** The installer registers your application executable to be called with the URL as a command-line argument (`%1`). For example, `your_app.exe "myapp://some/data"`.
    -   The Wails runtime for Windows (`v3/pkg/application/application_windows.go`) has been updated to check `os.Args` upon startup. If it detects an argument that looks like a URL (e.g., `os.Args[1]` contains `"://"`), it now emits the `events.Common.ApplicationLaunchedWithUrl` event with this URL.

-<Aside type="important">
+<Aside type="caution">
 For Windows, custom protocol schemes are typically only registered when your application is installed via an installer (like the one generated by Wails with NSIS). Running the bare executable might not have the schemes registered system-wide.
 </Aside>