feat(docs): seed Docusaurus site at /site, deploy to docs.fallout.build (#41)

.github/workflows/docs-deploy.yml

@@ -0,0 +1,66 @@
+# Hand-written (not auto-generated). Sibling to release.yml.
+#
+# Builds the Docusaurus site at /site/ and deploys to Cloudflare Pages
+# project "fallout-docs", which serves https://docs.fallout.build.
+#
+# The GitHub Pages slot on this repo is taken by fallout.build (apex).
+# Cloudflare Pages handles the docs subdomain so the apex stays untouched.
+#
+# This deploy is also the v13 CD-POC reference point: the shape here
+# (build artifact + authenticated push to an external system's API) is
+# exactly what ADR-0001's "tasks → REST" pattern targets. The deploy
+# stays minimal so it lifts cleanly into Fallout primitives later.
+#
+# Required repo secrets:
+#   - CLOUDFLARE_API_TOKEN — token with Pages:Edit scope
+#   - CLOUDFLARE_ACCOUNT_ID — Cloudflare account ID hosting the project
+
+name: docs-deploy
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'site/**'
+      - 'docs/**'
+      - '.github/workflows/docs-deploy.yml'
+
+permissions:
+  contents: read
+  deployments: write
+
+concurrency:
+  group: docs-deploy-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    name: build-and-deploy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: site/package-lock.json
+
+      - name: Install dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy site/build --project-name=fallout-docs --branch=main

.gitignore

@@ -1,6 +1,11 @@
 external
 nuke-global.*
 
+# Docs site (Docusaurus) — only commit source, never artifacts
+site/node_modules/
+site/build/
+site/.docusaurus/
+
 # Build Folders (you can keep bin if you'd like, to store dlls and pdbs)
 [Bb]in/
 [Oo]bj/

docs/01-getting-started/02-setup.md

@@ -126,8 +126,8 @@ You can deactivate linking of the above files by removing the `NukeRootDirectory
 
   <PropertyGroup>
     // highlight-start
-    <!-- <NukeRootDirectory>..</NukeRootDirectory> -->
-    <!-- <NukeScriptDirectory>..</NukeScriptDirectory> -->
+    {/* <NukeRootDirectory>..</NukeRootDirectory> */}
+    {/* <NukeScriptDirectory>..</NukeScriptDirectory> */}
     // highlight-end
   </PropertyGroup>
 

docs/02-fundamentals/05-targets.md

@@ -51,7 +51,7 @@ Specifying dependencies is essential to let targets run in a meaningful and pred
 <Tabs>
   <TabItem value="execution" label="Execution Dependencies">
 
-<!--Execution dependencies define that one target _must_ run before another target (unless it is skipped):-->
+{/*Execution dependencies define that one target _must_ run before another target (unless it is skipped):*/}
 
 Define that target `A` must run before target `B` unless `A` is skipped:
 
@@ -75,7 +75,7 @@ class Build : FalloutBuild
   </TabItem>
   <TabItem value="ordering" label="Ordering Dependencies">
 
-<!--Ordering dependencies define that one target _should_ run before/after another target _if_ they're both scheduled:-->
+{/*Ordering dependencies define that one target _should_ run before/after another target _if_ they're both scheduled:*/}
 
 Define that target `A` runs before target `B` if both are scheduled:
 
@@ -99,7 +99,7 @@ class Build : FalloutBuild
   </TabItem>
   <TabItem value="triggers" label="Trigger Dependencies">
 
-<!--Trigger dependencies define that one target _causes_ another target to run once it has succeeded:-->
+{/*Trigger dependencies define that one target _causes_ another target to run once it has succeeded:*/}
 
 Define that target `A` invokes target `B` once it completes:
 

docs/02-fundamentals/06-parameters.md

@@ -89,15 +89,15 @@ SET NUKE_MY_PARAMETER = <value>
 
 You can specify a parameter as a [target requirement](../02-fundamentals/05-targets.md#requirements) using the following shorthand syntax:
 
-<!-- snippet: parameters-requirements -->
+{/* snippet: parameters-requirements */}
 ```cs
 Target Deploy => _ => _
     .Requires(() => ApiKey)
     .Executes(() =>
     {
     });
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 :::tip
 Using the shorthand syntax allows you to provide the value interactively when the build is executed locally.
@@ -107,11 +107,11 @@ Using the shorthand syntax allows you to provide the value interactively when th
 
 When parameters are meant to hold **secret values** like passwords or authentication tokens, you can add the `Secret` attribute:
 
-<!-- snippet: parameters-secrets -->
+{/* snippet: parameters-secrets */}
 ```cs
 [Parameter] [Secret] readonly string NuGetApiKey;
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 Marking a parameter as a secret allows you to use the [secret management](../06-global-tool/02-secrets.md) through the global tool.
 
@@ -130,7 +130,7 @@ Unlisted parameters can be passed as normal and are still available through [she
 
 Parameters **support a wide range of primitive and complex types**, including their nullable and array counterparts:
 
-<!-- snippet: parameters-declaration -->
+{/* snippet: parameters-declaration */}
 ```cs
 [Parameter] readonly string StringValue;
 [Parameter] readonly bool BoolValue;
@@ -154,7 +154,7 @@ Target Print => _ => _
         Log.Information("AbsolutePath = {Value}", AbsolutePath);
     });
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 :::note
 By default, the whitespace character is used to pass multiple values for an array parameter. You can quote your values to treat them as single elements for the parameters. Additionally, you can provide a custom separator through the attribute (whitespace will still work as a separator):

docs/02-fundamentals/10-logging.md

@@ -68,11 +68,11 @@ Or by setting it directly in the build implementation:
 <Tabs groupId="logging">
   <TabItem value="trace" label="Trace" default>
 
-<!-- snippet: logging -->
+{/* snippet: logging */}
 ```csharp
 Logging.Level = LogLevel.Trace;
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
   </TabItem>
   <TabItem value="normal" label="Normal">

docs/03-common/03-paths.md

@@ -6,19 +6,19 @@ Referencing files and directories seems like a trivial task. Nevertheless, devel
 
 Central to the idea of absolute paths is the `AbsolutePath` type and the `FalloutBuild.RootDirectory` property. From there on, you can easily construct paths through the [overloaded division operator](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/operator-overloading):
 
-<!-- snippet: path-construction-basic -->
+{/* snippet: path-construction-basic */}
 ```cs
 AbsolutePath SourceDirectory => RootDirectory / "src";
 AbsolutePath OutputDirectory => RootDirectory / "output";
 AbsolutePath IndexFile => RootDirectory / "docs" / "index.md";
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 ## Common Methods
 
 While `AbsolutePath` is agnostic to whether it points to a file or directory, it provides several commonly used methods for interaction:
 
-<!-- snippet: path-construction-common-methods -->
+{/* snippet: path-construction-common-methods */}
 ```cs
 // Get names
 var nameWithExtension = IndexFile.Name;
@@ -38,13 +38,13 @@ var directoryExists = SourceDirectory.DirectoryExists();
 var fileExists = IndexFile.FileExists();
 var pathExists = (RootDirectory / "dirOrFile").Exists(); // checks for both
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 ## Relative Paths
 
 Occasionally, you may actually want relative paths, for instance, to include them in manifest files that get shipped with your artifacts. In this case, you can make use of `RelativePath`, which uses the path separator dictated by the operating system, or one of types `WinRelativePath` or `UnixRelativePath`, which enforce using backslash or slash respectively:
 
-<!-- snippet: path-construction-relative-paths -->
+{/* snippet: path-construction-relative-paths */}
 ```cs
 // Get the relative path to the index file
 var indexRelativeFile = RootDirectory.GetRelativePathTo(IndexFile);
@@ -53,7 +53,7 @@ var indexRelativeFile = RootDirectory.GetRelativePathTo(IndexFile);
 var indexUnixRelativePath1 = RootDirectory.GetUnixRelativePathTo(IndexFile);
 var indexUnixRelativePath2 = (UnixRelativePath)indexRelativeFile;
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 All relative path types support using the division operator.
 
@@ -85,7 +85,7 @@ source.CopyToDirectory(target, ExistsPolicy.DirectoryMerge | ExistsPolicy.FileFa
 
 Through the integrated [Glob](https://github.com/kthompson/glob) NuGet package, you can use [globbing patterns](https://en.wikipedia.org/wiki/Glob_(programming)) to collect files or directories from a base directory:
 
-<!-- snippet: path-construction-globbing -->
+{/* snippet: path-construction-globbing */}
 ```cs
 // Collect all package files from the output directory
 var packageFiles = OutputDirectory.GlobFiles("*.nupkg");
@@ -95,4 +95,4 @@ SourceDirectory
     .GlobDirectories("**/{obj,bin}", otherPatterns)
     .DeleteDirectories();
 ```
-<!-- endSnippet -->
+{/* endSnippet */}

docs/03-common/05-repository.md

@@ -6,7 +6,7 @@ Having knowledge about the current branch, applied tags, and the repository orig
 
 You can use the `GitRepositoryAttribute` on a `GitRepository` field or property, to automatically load all relevant information for the current revision at the beginning of build execution:
 
-<!-- snippet: repository-information -->
+{/* snippet: repository-information */}
 ```cs
 [GitRepository] readonly GitRepository Repository;
 
@@ -26,12 +26,12 @@ Target Print => _ => _
         Log.Information("SSH URL = {Value}", Repository.SshUrl);
     });
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 :::tip
 Repository insights allow you to design your targets in a flexible manner using [requirements](../02-fundamentals/05-targets.md#requirements), [conditional execution](../02-fundamentals/05-targets.md#conditional-execution), or hybrid implementations:
 
-<!-- snippet: repository-information-use-cases -->
+{/* snippet: repository-information-use-cases */}
 ```cs
 [GitRepository] readonly GitRepository Repository;
 string OriginalRepositoryUrl => "https://github.com/ChrisonSimtian/Fallout";
@@ -51,7 +51,7 @@ Target Hotfix => _ => _
             CreateHotfix();
     });
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 :::tip
 
 :::info
@@ -69,7 +69,7 @@ The only difference between `FromUrl` and `FromLocalDirectory` is that the latte
 
 As one of the most popular Git hosting services, NUKE provides several methods to retrieve GitHub-specific **identifiers and links** from a repository:
 
-<!-- snippet: repository-information-github -->
+{/* snippet: repository-information-github */}
 ```cs
 // Get repository owner and name
 var (owner, name) = (Repository.GetGitHubOwner(), Repository.GetGitHubName());
@@ -83,23 +83,23 @@ var comparisonUrl = Repository.GetGitHubCompareTagsUrl("1.0.1", "1.0.2");
 // Get file download URL
 var downloadUrl = Repository.GetGitHubDownloadUrl(RootDirectory / "CHANGELOG.md", branch: "main");
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 You can also further interact with the repository using the [Octokit.NET](https://github.com/octokit/octokit.net) integration:
 
-<!-- snippet: repository-information-github-octokit -->
+{/* snippet: repository-information-github-octokit */}
 ```cs
 // Get the default branch
 var defaultBranch = Repository.GetDefaultBranch();
 
 // Get the latest release
 var latestRelease = Repository.GetLatestRelease(includePrerelease: false);
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 For certain operations, you may initialize an **authorized client**:
 
-<!-- snippet: repository-information-github-octokit-authed -->
+{/* snippet: repository-information-github-octokit-authed */}
 ```cs
 // Set credentials for authorized actions
 var credentials = new Credentials(GitHubActions.Instance.Token);
@@ -111,4 +111,4 @@ GitHubTasks.GitHubClient = new GitHubClient(
 Repository.CreateGitHubMilestone("5.1.0");
 Repository.CloseGitHubMilestone("5.1.0", enableIssueChecks: true);
 ```
-<!-- endSnippet -->
+{/* endSnippet */}

docs/03-common/08-cli-tools.md

@@ -129,8 +129,8 @@ You can also use the fluent interfaces to manipulate the process invocation, inc
 All fluent interfaces implement a variation of the [builder pattern](https://en.wikipedia.org/wiki/Builder_pattern), in which every fluent call will create an immutable copy of the current `ToolSettings` instance with the intended changes applied. This enables great flexibility in composing similar process invocations.
 :::
 
-<!-- TODO: website -->
-<!-- Using any IDE, an individual fluent interface can easily be discovered via code completion. Most importantly, you can look up the original documentation right from where you are: -->
+{/* TODO: website */}
+{/* Using any IDE, an individual fluent interface can easily be discovered via code completion. Most importantly, you can look up the original documentation right from where you are: */}
 
 ### Conditional Modifications
 
@@ -195,15 +195,15 @@ MSBuildTasks.MSBuild(_ => _
         .Add("/r")));
 ```
 
-<!--
+{/*
     SetToolPath
     SetWorkingDirectory
     SetExecutionTimeout
     SetEnvironmentVariables
     LogOutput
     When
     SetArgumentConfigurator
--->
+*/}
 
 ### Exit Code Handling
 
@@ -280,7 +280,7 @@ class Build : FalloutBuild
 
 Many of the most popular tools are already implemented. In case a certain tool is not yet supported with a proper CLI task class, NUKE allows you to use the following **injection attributes** to load them:
 
-<!-- snippet: tool-invocation-lightweight -->
+{/* snippet: tool-invocation-lightweight */}
 ```csharp
 [PathVariable]
 readonly Tool Git;
@@ -302,11 +302,11 @@ readonly Tool CorFlags;
     unixPath: "gradlew")]
 readonly Tool Gradle;
 ```
-<!-- endSnippet -->
+{/* endSnippet */}
 
 The injected `Tool` delegate allows passing arguments, working directory, environment variables and many more process-specific options:
 
-<!-- snippet: tool-invocation-lightweight-usage -->
+{/* snippet: tool-invocation-lightweight-usage */}
 ```csharp
 // Pass arguments with string interpolation
 Git($"checkout -b {Branch}");
@@ -323,4 +323,4 @@ CorFlags(
 // Requires: <PackageDownload Include="Redth.Net.Maui.Check" Version="0.10.0" />
 MauiCheck?.Invoke($"--fix --preview");
 ```
-<!-- endSnippet -->
+{/* endSnippet */}