Add Doc Site v1

[mildronize]

Setup Tasks

• Setup Doc Site: Vitepress
• Setup Landing Page, Key Highlight
• Setup Vitepress Structure
• Setup API Gen: https://typedoc-plugin-markdown.org/plugins/vitepress
• Write github Actions to deploy to Azure Static Web App
• Setup domain as https://kubricate.thaitype.dev
• Support SEO, see: https://typescript-is-like-csharp.chrlschn.dev/

Content Tasks

Guide Section

ℹ️ Introduction

• Why Kubricate

  • Intro – Short mission statement
  • The Problem – Real-world pain of YAML, secrets, and drift
  • The Solution – Kubricate in plain terms (without code yet)
  • How It Works – Stacks + Secrets + CLI explained with metaphors
  • Key Benefits – Now explain type safety, plugin system, CI/CD
  • Comparison Table – ESO / Vault etc.
  • What You Get
  • Next Steps

• Quickstart

  • Minimal step-by-step guide
  • Define a simple AppStack
  • Run kubricate generate
  • Show YAML output

ℹ️ Tutorials

• Understand the Workflow
• Start from Template
• Generate & Apply
• Build Your Template
• Working with Secrets

ℹ️ How-to Guides

• Multi-env Stacks

  • Use .from() to adjust config
  • Support multiple environments: dev/staging/prod

• Override Configs

  • Show how to override stack fields
  • Example: image tags, resource limits

• Secret Conflict Handling

  • Default: autoMerge at intraProvider
  • Briefly introduce other strategies

• Stack Output Modes

  • Explain outputMode in config:
    • stack
    • resource
    • flat
    • stdout
  • Real-world use cases

• Single SecretManager

  • Multiple Providers and Connectors
  • Best practices for secret injection

• Scaling with SecretRegistry

  • Use cases for multiple SecretManagers
  • Namespace/stack scaling best practices

ℹ️ Core Concepts

• Stacks

  • Type-safe infra
  • Grouping resources with ResourceComposer

• SecretManager

  • Load via Connectors
  • Inject via Providers
  • Secret lifecycle overview

• Connectors

  • Load secrets from .env, JSON, Vault, etc.

• Providers

  • Map secrets into K8s resources
  • E.g. OpaqueSecretProvider

• SecretRegistry

  • Manage multiple SecretManagers
  • Scale across stacks/domains

ℹ️ Advanced Usage

• Secret Merge Strategy

  • Explain default (autoMerge)
  • Other strategies: error, overwrite, skip
  • Real conflict examples

• Metadata Injection

  • Explain injected metadata:
    • stack-id
    • resource-id
    • managed-at
  • Benefits in GitOps traceability

• Custom Connector

  • Show how to implement load()
  • Register with SecretManager
  • Example: API-based loader

• Custom Provider

  • Implement custom output format
  • Example: CRD or third-party format

ℹ️ Architecture

• Stack Build Flow

  • Flow from Stack → ResourceComposer → Output
  • Emphasize type-safety and no runtime

• Secret Orchestration

  • Flow: Connector → Provider → Merge → Injection
  • Use SecretsOrchestrator

• CLI Execution Flow

  • Load config
  • Init stacks
  • Execute commands (generate, secret apply)

• Injection System

  • Builders generate injection targets
  • Providers resolve to manifests

ℹ️ Contributing

• Local Dev Setup

  • Monorepo layout
  • Required tools (pnpm)
  • Dev scripts

• Codebase Structure

  • Overview of packages:
    • @kubricate/core
    • toolkit, cli, etc.

• Testing & Validation

  • Test custom stacks/connectors/providers
  • Unit testing tips and practices

• Release Process

  • Versioning flow
  • Publishing to npm
  • Tagging, changelog generation

• Roadmap

  • Future features:
    • hydration
    • audit CLI
    • registry plugins

Reference Sections

• Draft Content Outline
• API Gen for
  • kubricate
  • @kubricate/core
  • @kubricate/plugin-env
  • @kubricate/plugin-kubernetes
  • @kubricate/stacks
  • @kubricate/toolkit

[mildronize]

Consider using https://fumadocs.dev/ as doc site