Add VitePress documentation site for JasperFx

.github/workflows/publish-docs.yml

@@ -0,0 +1,57 @@
+name: Publish Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'src/DocSamples/**'
+      - 'mdsnippets.json'
+      - 'package.json'
+  workflow_dispatch:
+
+env:
+  DOTNET_CLI_TELEMETRY_OPTOUT: 1
+  DOTNET_SKIP_FIRST_TIME_EXPERIENCE: 1
+
+jobs:
+  publish:
+    name: Build and deploy docs to Netlify
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install .NET 10.0.x
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Build DocSamples
+        run: dotnet build src/DocSamples/DocSamples.csproj -c Release
+
+      - name: Install mdsnippets
+        run: dotnet tool install -g markdownSnippets.tool
+
+      - name: Run mdsnippets
+        run: mdsnippets
+
+      - name: Install npm dependencies
+        run: npm ci
+
+      - name: Build VitePress site
+        run: npx vitepress build docs
+
+      - name: Deploy to Netlify
+        uses: nwtgck/actions-netlify@v3
+        with:
+          publish-dir: docs/.vitepress/dist
+          production-deploy: true
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

.gitignore

@@ -399,3 +399,7 @@ FodyWeavers.xsd
 .idea/
 .DS_Store
 src/CommandLineRunner/description.txt
+
+# VitePress documentation
+docs/.vitepress/cache
+docs/.vitepress/dist

docs/.gitignore

@@ -0,0 +1,3 @@
+.vitepress/cache
+.vitepress/dist
+node_modules

docs/.vitepress/config.ts

@@ -0,0 +1,108 @@
+import { defineConfig } from 'vitepress'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+
+export default withMermaid(
+  defineConfig({
+    title: 'JasperFx',
+    description: 'The foundational .NET library behind the Critter Stack',
+    head: [
+      ['link', { rel: 'icon', href: '/jasperfx-logo.png' }]
+    ],
+
+    themeConfig: {
+      logo: '/jasperfx-logo.png',
+
+      nav: [
+        { text: 'Guide', link: '/guide/' },
+        { text: 'Code Generation', link: '/codegen/' },
+        { text: 'Command Line', link: '/cli/' },
+        { text: 'Configuration', link: '/configuration/critter-stack-defaults' },
+        {
+          text: 'Ecosystem',
+          items: [
+            { text: 'Marten', link: 'https://martendb.io' },
+            { text: 'Wolverine', link: 'https://wolverinefx.io' },
+            { text: 'Weasel', link: 'https://weasel.jasperfx.net' },
+            { text: 'GitHub', link: 'https://github.com/JasperFx/jasperfx' }
+          ]
+        }
+      ],
+
+      sidebar: [
+        {
+          text: 'Getting Started',
+          collapsed: false,
+          items: [
+            { text: 'Introduction', link: '/guide/' },
+            { text: 'Installation', link: '/guide/installation' },
+            { text: 'Quick Start', link: '/guide/quickstart' }
+          ]
+        },
+        {
+          text: 'Code Generation',
+          collapsed: false,
+          items: [
+            { text: 'Overview & Architecture', link: '/codegen/' },
+            { text: 'Frames', link: '/codegen/frames' },
+            { text: 'Variables', link: '/codegen/variables' },
+            { text: 'MethodCall', link: '/codegen/method-call' },
+            { text: 'Generated Types & Methods', link: '/codegen/generated-types' },
+            { text: 'Built-in Frames', link: '/codegen/built-in-frames' },
+            { text: 'CLI: codegen Command', link: '/codegen/cli' }
+          ]
+        },
+        {
+          text: 'Command Line',
+          collapsed: false,
+          items: [
+            { text: 'Setup & Integration', link: '/cli/' },
+            { text: 'Writing Commands', link: '/cli/writing-commands' },
+            { text: 'Arguments & Flags', link: '/cli/arguments-flags' },
+            { text: 'Environment Checks', link: '/cli/environment-checks' },
+            { text: 'Describe Command', link: '/cli/describe' }
+          ]
+        },
+        {
+          text: 'Configuration',
+          collapsed: true,
+          items: [
+            { text: 'CritterStackDefaults', link: '/configuration/critter-stack-defaults' },
+            { text: 'JasperFxOptions', link: '/configuration/jasperfx-options' }
+          ]
+        },
+        {
+          text: 'Extension Methods',
+          collapsed: true,
+          items: [
+            { text: 'Overview', link: '/extensions/' },
+            { text: 'String Extensions', link: '/extensions/string-extensions' },
+            { text: 'Enumerable Extensions', link: '/extensions/enumerable-extensions' },
+            { text: 'Reflection Extensions', link: '/extensions/reflection-extensions' }
+          ]
+        }
+      ],
+
+      socialLinks: [
+        { icon: 'github', link: 'https://github.com/JasperFx/jasperfx' }
+      ],
+
+      editLink: {
+        pattern: 'https://github.com/JasperFx/jasperfx/edit/main/docs/:path'
+      },
+
+      footer: {
+        message: 'Released under the MIT License.',
+        copyright: 'Copyright JasperFx Software'
+      },
+
+      search: {
+        provider: 'local'
+      }
+    },
+
+    mermaid: {},
+    mermaidPlugin: {
+      class: 'mermaid'
+    }
+  })
+)

docs/.vitepress/theme/custom.css

@@ -0,0 +1,30 @@
+:root {
+  --vp-c-brand-1: #C26A1A;
+  --vp-c-brand-2: #D4782B;
+  --vp-c-brand-3: #E08A3D;
+  --vp-c-brand-soft: rgba(194, 106, 26, 0.14);
+
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(135deg, #C26A1A 0%, #E08A3D 100%);
+  --vp-home-hero-image-background-image: linear-gradient(135deg, rgba(194, 106, 26, 0.3) 0%, rgba(224, 138, 61, 0.2) 100%);
+  --vp-home-hero-image-filter: blur(44px);
+
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: #fff;
+  --vp-button-brand-bg: #C26A1A;
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: #fff;
+  --vp-button-brand-hover-bg: #D4782B;
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: #fff;
+  --vp-button-brand-active-bg: #A85A16;
+}
+
+.dark {
+  --vp-c-brand-1: #D4782B;
+  --vp-c-brand-2: #E08A3D;
+  --vp-c-brand-3: #ECA050;
+  --vp-c-brand-soft: rgba(212, 120, 43, 0.16);
+
+  --vp-home-hero-image-background-image: linear-gradient(135deg, rgba(194, 106, 26, 0.2) 0%, rgba(224, 138, 61, 0.15) 100%);
+}

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme

docs/cli/arguments-flags.md

@@ -0,0 +1,100 @@
+# Arguments and Flags
+
+Command inputs are plain C# classes whose properties are mapped to arguments and flags.
+
+## Defining an Input Class
+
+<!-- snippet: sample_build_input -->
+<a id='snippet-sample_build_input'></a>
+```cs
+public class BuildInput
+{
+    [Description("The target configuration")]
+    public string Configuration { get; set; } = "Debug";
+
+    [Description("The output directory")]
+    public string OutputPath { get; set; } = "./bin";
+
+    [FlagAlias("verbose", 'v')]
+    [Description("Enable verbose output")]
+    public bool VerboseFlag { get; set; }
+
+    [FlagAlias("force", 'f')]
+    [Description("Force a clean rebuild")]
+    public bool ForceFlag { get; set; }
+
+    [Description("Maximum degree of parallelism")]
+    public int ParallelCount { get; set; } = 4;
+}
+```
+<sup><a href='https://github.com/JasperFx/jasperfx/blob/master/src/DocSamples/ArgumentFlagSamples.cs#L5-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_build_input' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+<a id='snippet-sample_build_input'></a>
+```cs
+public class BuildInput
+{
+    [Description("The target configuration")]
+    public string Configuration { get; set; } = "Debug";
+
+    [Description("The output directory")]
+    public string OutputPath { get; set; } = "./bin";
+
+    [FlagAlias("verbose", 'v')]
+    [Description("Enable verbose output")]
+    public bool VerboseFlag { get; set; }
+
+    [FlagAlias("force", 'f')]
+    [Description("Force a clean rebuild")]
+    public bool ForceFlag { get; set; }
+
+    [Description("Maximum degree of parallelism")]
+    public int ParallelCount { get; set; } = 4;
+}
+```
+<sup><a href='https://github.com/JasperFx/jasperfx/blob/master/src/DocSamples/ArgumentFlagSamples.cs#L5-L25' title='Snippet source file'>snippet source</a> | <a href='#snippet-sample_build_input' title='Start of snippet'>anchor</a></sup>
+<!-- endSnippet -->
+
+## Arguments
+
+Public properties that are not suffixed with `Flag` are treated as positional arguments. They are matched in the order they appear on the class.
+
+- **Required arguments** -- Non-nullable properties without a default value
+- **Optional arguments** -- Properties with a default value
+
+## Flags
+
+Properties whose names end with `Flag` are treated as command line flags (options).
+
+### Flag Aliases
+
+Use `[FlagAlias]` to define short and long flag names:
+
+```csharp
+[FlagAlias("verbose", 'v')]
+public bool VerboseFlag { get; set; }
+```
+
+This allows both `--verbose` and `-v` on the command line.
+
+### Flag Types
+
+| .NET Type | CLI Syntax | Example |
+|-----------|-----------|---------|
+| `bool` | `--flag` | `--verbose` |
+| `string` | `--flag value` | `--output ./bin` |
+| `int` | `--flag value` | `--parallel 8` |
+| `Enum` | `--flag value` | `--level Debug` |
+
+## Description Attribute
+
+Use `[Description]` on properties to provide help text displayed in the CLI:
+
+```csharp
+[Description("The target configuration")]
+public string Configuration { get; set; } = "Debug";
+```
+
+## Next Steps
+
+- [Writing Commands](/cli/writing-commands) -- Build commands using input classes
+- [Environment Checks](/cli/environment-checks) -- Startup validation