feat(offline): self-host CDN assets by default on production builds

Change optimize.offline to a tri-state (null/true/false). When unset it
now self-hosts external assets automatically for production builds
(--prod, deploy) while skipping serve/dev for fast local iteration.
Explicit true/false still force the behaviour either way.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Netdocs

docs-site/docs/setup/building-for-offline-usage.md

@@ -5,24 +5,34 @@ title: Building for offline usage
 # Building for offline usage
 
 Sometimes a site can't be hosted on the web — it ships on a USB stick, lives on an air-gapped
-network, or is opened straight from disk with `file://`. By default Netdocs loads a few assets
-from CDNs (syntax highlighting, Mermaid, web fonts, emoji). Offline mode **self-hosts all of
-them** so the built site is fully self-contained.
+network, or is opened straight from disk with `file://`. Netdocs loads a few assets from CDNs
+(syntax highlighting, Mermaid, web fonts, emoji) during development; offline mode **self-hosts all
+of them** so the built site is fully self-contained. It runs automatically on production builds.
 
 ## Enable it
 
-Set `optimize.offline` in `appsettings.json`:
+Offline self-hosting is **on by default for production builds** — `netdocs build --prod` (and
+`deploy`) self-host CDN assets automatically, while `serve`/dev builds skip it so local iteration
+stays fast. You don't have to configure anything to get a self-contained published site.
+
+To control it explicitly, set `optimize.offline` in `appsettings.json`:
 
 ```json
 "optimize": {
   "offline": true
 }
 ```
 
+| Value | Behaviour |
+|---|---|
+| omitted / `null` | **Default.** Self-host on production builds (`--prod`, `deploy`), skip during `serve`. |
+| `true` | Always self-host, including local and dev builds. |
+| `false` | Never self-host (keep CDN references). |
+
 Then build as usual:
 
 ```bash
-netdocs build
+netdocs build --prod
 ```
 
 ```

src/Netdocs.Abstractions/SiteConfig.cs

@@ -205,8 +205,13 @@ public sealed class OptimizeConfig
     /// <c>assets/external/</c>, and rewrites the pages to reference the local copies so the site
     /// works without internet (including from <c>file://</c>). Requires network access at build
     /// time; assets that fail to download keep their CDN URL and log a warning.
+    /// <para>
+    /// Tri-state: <c>null</c> (default) self-hosts on production builds but not during
+    /// <c>serve</c>/dev, so published sites are resilient while local iteration stays fast and
+    /// offline. Set <c>true</c> to always self-host, or <c>false</c> to never self-host.
+    /// </para>
     /// </summary>
-    public bool Offline { get; set; }
+    public bool? Offline { get; set; }
 }
 
 /// <summary>

src/Netdocs.Cli/NewCommand.cs

@@ -156,9 +156,10 @@ public static async Task<int> RunAsync(string[] args)
       "minifyJs": false,
       "convertImagesToWebp": false,
       "webpQuality": 80,
-      // Self-host every CDN asset (highlight.js, Mermaid, fonts, emoji) so the
-      // built site runs from file:// — requires network access at build time.
-      "offline": false
+      // Self-host every CDN asset (highlight.js, Mermaid, fonts, emoji) so the built
+      // site runs from file://. Requires network access at build time. Omit for the
+      // default (self-host on production builds only); set true/false to force it.
+      "offline": null
     },
 
     // --- Build-time validation -------------------------------------------------------

src/Netdocs.Core/BuildEngine.cs

@@ -224,7 +224,9 @@ public async Task<SiteContext> BuildAsync(CancellationToken ct = default)
         }
 
         // 13b. Offline self-hosting: download external CDN assets and rewrite pages to local copies.
-        if (config.Optimize.Offline)
+        // Tri-state: null => self-host on production builds only (not serve/dev); true/false forces it.
+        var offline = config.Optimize.Offline ?? (options.IsProduction && !options.IsServe);
+        if (offline)
             using (Measure("13b. self-host assets"))
                 await Optimization.SelfHostAssets.RunAsync(site, _log, ct);
 

src/Netdocs.Core/Configuration/JsonConfigLoader.cs

@@ -76,7 +76,8 @@ public static SiteConfig Load(string appSettingsPath)
         MinifyJs = m.Get("minifyJs").AsBool(false),
         ConvertImagesToWebp = m.Get("convertImagesToWebp").AsBool(false),
         WebpQuality = m.Get("webpQuality").AsInt(80),
-        Offline = m.Get("offline").AsBool(false),
+        // Tri-state: absent => null (auto: production-only). Present => explicit true/false.
+        Offline = m.Get("offline") is { } off ? off.AsBool(false) : null,
     };
 
     private static SlugifyConfig ParseSlugify(IReadOnlyDictionary<string, object?> m) => new()