Create a Comprehensive README

.gitignore

@@ -22,3 +22,4 @@ pnpm-debug.log*
 
 # macOS-specific files
 .DS_Store
+CLAUDE.md

README.md

@@ -1,5 +1,72 @@
-# Scalekit documentation
+# Scalekit Documentation
 
-Welcome to the source for Scalekit documentation.
+This repository contains the source code for the official Scalekit documentation, available at [docs.scalekit.com](https://docs.scalekit.com).
 
-> Note: This README is work in progress.
+The documentation is built using [Astro](https://astro.build/) and the [Starlight](https://starlight.astro.build/) theme.
+
+## Getting Started
+
+Follow these instructions to set up a local development environment.
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) (version 20.x or higher recommended)
+- [pnpm](https://pnpm.io/)
+
+### Installation
+
+1.  Clone the repository:
+
+    ```bash
+    git clone https://github.com/scalekit-inc/developer-docs.git
+    cd developer-docs
+    ```
+
+2.  Install the dependencies using pnpm:
+    ```bash
+    pnpm install
+    ```
+
+## Development
+
+To start the local development server, run the following command:
+
+```bash
+pnpm dev
+```
+
+This will start a development server, typically at `http://localhost:4321`. The server will automatically reload when you make changes to the source files.
+
+## Building
+
+To create a production-ready build of the website, run the following command:
+
+```bash
+pnpm build
+```
+
+The output will be generated in the `dist/` directory.
+
+## Key Technologies
+
+- [Astro](https://astro.build/): The web framework for building the documentation site.
+- [Starlight](https://starlight.astro.build/): An official Astro theme for building documentation websites.
+- [React](https://react.dev/): Used for some interactive components.
+- [Vue](https://vuejs.org/): Used for some interactive components, including the API reference.
+- [Tailwind CSS](https://tailwindcss.com/): For styling.
+- [MDX](https://mdxjs.com/): Allows for the use of JSX components within Markdown files.
+
+## Project Structure
+
+- `src/content/docs/`: Contains the Markdown and MDX files for the documentation pages. This is where most of the content lives.
+- `src/components/`: Contains reusable Astro, React, and Vue components.
+- `src/styles/`: Contains custom CSS and Tailwind CSS configuration.
+- `astro.config.mjs`: The main configuration file for Astro and Starlight.
+- `public/`: Contains static assets like images, fonts, and Swagger API files.
+- `package.json`: Defines the project's dependencies and scripts.
+
+## Contributing
+
+Contributions to the documentation are welcome! You can suggest changes by opening a pull request.
+
+The "Edit this page" link on each documentation page will take you directly to the corresponding file in the GitHub repository, making it easy to propose edits.

astro.config.mjs

@@ -14,14 +14,15 @@ import starlightLlmsTxt from 'starlight-llms-txt'
 import starlightVideos from 'starlight-videos'
 import { sidebar as sidebarConfig, topics } from './src/configs/sidebar.config'
 import { redirects } from './src/configs/redirects.config'
-
+import mermaid from 'astro-mermaid'
 import tailwindcss from '@tailwindcss/vite'
 
 // https://astro.build/config
 export default defineConfig({
   site: 'https://docs.scalekit.com',
   redirects,
   integrations: [
+    mermaid(),
     starlight({
       title: 'Scalekit Docs',
       routeMiddleware: './src/routeData.ts',

package.json

@@ -32,6 +32,9 @@
     "astro": "^5.12.2",
     "astro-og-canvas": "^0.7.0",
     "canvaskit-wasm": "0.39.1",
+    "astro": "^5.12.2",
+    "astro-mermaid": "^1.0.4",
+    "mermaid": "^11.9.0",
     "pnpm": "^10.12.4",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",

src/components/overrides/Head.astro

@@ -1,7 +1,7 @@
 ---
-import Default from '@astrojs/starlight/components/Head.astro';
+import Default from '@astrojs/starlight/components/Head.astro'
 ---
 
 <Default>
   <slot />
-</Default>
+</Default>

src/components/overrides/MarkdownContent.astro

@@ -5,4 +5,4 @@ import ImageZoom from 'starlight-image-zoom/components/ImageZoom.astro'
 
 <ImageZoom />
 <p>Custom content in the MarkdownContent override</p>
-<Default><slot /></Default>
+<Default><slot /></Default>

src/components/overrides/Sidebar.astro

@@ -1,10 +1,10 @@
 ---
 // src/components/Sidebar.astro
-import Default from "@astrojs/starlight/components/Sidebar.astro";
-import TopicsDropdown from "starlight-sidebar-topics-dropdown/TopicsDropdown.astro";
+import Default from '@astrojs/starlight/components/Sidebar.astro'
+import TopicsDropdown from 'starlight-sidebar-topics-dropdown/TopicsDropdown.astro'
 ---
 
 {/* Render the topics dropdown menu. */}
 <TopicsDropdown />
 {/* Render the default sidebar. */}
-<Default><slot /></Default>
+<Default><slot /></Default>

src/components/overrides/SocialIcons.astro

@@ -1,15 +1,19 @@
 ---
-import Default from '@astrojs/starlight/components/SocialIcons.astro';
+import Default from '@astrojs/starlight/components/SocialIcons.astro'
 ---
 
 <Default><slot /></Default>
 
-<div class="flex gap-4 items-center">
-  <button id="auth-button" class="inline-flex items-center justify-center px-4 py-2 text-sm font-semibold rounded-md bg-[var(--sl-color-accent)] text-white hover:bg-[var(--sl-color-accent-high)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-[var(--sl-color-accent)] focus-visible:outline-offset-2 disabled:bg-gray-200 disabled:text-gray-500 disabled:cursor-not-allowed transition-colors duration-200 rounded-[0.2rem]">Start building auth</button>
+<div class="flex items-center gap-4">
+  <button
+    id="auth-button"
+    class="inline-flex items-center justify-center rounded-[0.2rem] rounded-md bg-[var(--sl-color-accent)] px-4 py-2 text-sm font-semibold text-white transition-colors duration-200 hover:bg-[var(--sl-color-accent-high)] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--sl-color-accent)] disabled:cursor-not-allowed disabled:bg-gray-200 disabled:text-gray-500"
+    >Start building auth</button
+  >
 </div>
 
 <script>
   document.getElementById('auth-button')?.addEventListener('click', () => {
-    window.location.href = 'https://www.scalekit.com';
-  });
+    window.location.href = 'https://www.scalekit.com'
+  })
 </script>

src/components/ui/FlashNote.astro

@@ -1,35 +1,33 @@
 ---
 interface Props {
-  className?: string;
-  size?: 'sm' | 'md' | 'lg';
-  centered?: boolean;
-  color?: 'default' | 'accent' | 'warning' | 'success';
+  className?: string
+  size?: 'sm' | 'md' | 'lg'
+  centered?: boolean
+  color?: 'default' | 'accent' | 'warning' | 'success'
 }
 
-const {
-  className = '',
-  size = 'md',
-  centered = false,
-  color = 'default'
-} = Astro.props;
+const { className = '', size = 'md', centered = false, color = 'default' } = Astro.props
 
 const sizeClasses = {
   sm: 'text-lg py-1 px-3',
   md: 'text-xl py-2 px-4',
-  lg: 'text-2xl py-3 px-5'
-};
+  lg: 'text-2xl py-3 px-5',
+}
 
-const alignment = centered ? 'text-center mx-auto' : 'text-left';
+const alignment = centered ? 'text-center mx-auto' : 'text-left'
 
 const colorClasses = {
-  default: 'bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 border-black dark:border-gray-700',
+  default:
+    'bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-100 border-black dark:border-gray-700',
   accent: 'bg-accent-100 dark:bg-accent-950 text-accent-900 dark:text-accent-100 border-accent-600',
-  warning: 'bg-yellow-100 dark:bg-yellow-900 text-yellow-900 dark:text-yellow-100 border-yellow-500',
-  success: 'bg-green-100 dark:bg-green-900 text-green-900 dark:text-green-100 border-green-500'
-};
+  warning:
+    'bg-yellow-100 dark:bg-yellow-900 text-yellow-900 dark:text-yellow-100 border-yellow-500',
+  success: 'bg-green-100 dark:bg-green-900 text-green-900 dark:text-green-100 border-green-500',
+}
 ---
 
-<h3 class={`
+<h3
+  class={`
   inline-block
   font-heading
   font-bold
@@ -47,6 +45,7 @@ const colorClasses = {
   ${alignment}
   ${colorClasses[color]}
   ${className}
-`}>
+`}
+>
   <slot />
-</h3>
+</h3>

src/components/ui/ResponsiveCardGrid.astro

@@ -1,9 +1,9 @@
 ---
 interface Props {
-  className?: string;
+  className?: string
 }
 
-const { className = '' } = Astro.props;
+const { className = '' } = Astro.props
 ---
 
 <div class={`responsive-card-grid ${className}`}>
@@ -38,4 +38,4 @@ const { className = '' } = Astro.props;
       grid-template-columns: repeat(4, 1fr);
     }
   }
-</style>
+</style>

src/components/ui/SideBySide.astro

@@ -1,18 +1,13 @@
 ---
 // SideBySide.astro - A reusable component for side-by-side content
 export interface Props {
-  class?: string;
-  gap?: string;
-  leftClass?: string;
-  rightClass?: string;
+  class?: string
+  gap?: string
+  leftClass?: string
+  rightClass?: string
 }
 
-const {
-  class: className = '',
-  gap = '2rem',
-  leftClass = '',
-  rightClass = ''
-} = Astro.props;
+const { class: className = '', gap = '2rem', leftClass = '', rightClass = '' } = Astro.props
 ---
 
 <div class={`side-by-side ${className}`} style={`--gap: ${gap}`}>
@@ -43,4 +38,4 @@ const {
       grid-template-columns: 1fr;
     }
   }
-</style>
+</style>

src/components/ui/SimpleCode.astro

@@ -1,13 +1,13 @@
 ---
 interface Props {
-  className?: string;
+  className?: string
 }
 
-const { className = '' } = Astro.props;
+const { className = '' } = Astro.props
 ---
 
 <code
   class={`${className} simple_code font-mono text-sm px-1.5 py-0.5 dark:bg-gray-800 text-gray-800 dark:text-gray-200 rounded`}
 >
   <slot />
-</code>
+</code>

src/components/ui/Subtitle.astro

@@ -1,41 +1,38 @@
 ---
 interface Props {
-  className?: string;
-  size?: 'sm' | 'md' | 'lg';
-  centered?: boolean;
-  color?: 'default' | 'accent' | 'muted';
+  className?: string
+  size?: 'sm' | 'md' | 'lg'
+  centered?: boolean
+  color?: 'default' | 'accent' | 'muted'
 }
 
-const {
-  className = '',
-  size = 'md',
-  centered = false,
-  color = 'default'
-} = Astro.props;
+const { className = '', size = 'md', centered = false, color = 'default' } = Astro.props
 
 const sizeClasses = {
   sm: 'text-lg',
   md: 'text-xl',
-  lg: 'text-2xl'
-};
+  lg: 'text-2xl',
+}
 
-const alignment = centered ? 'text-center' : 'text-left';
+const alignment = centered ? 'text-center' : 'text-left'
 
 const colorClasses = {
   default: 'text-gray-700 dark:text-gray-300',
   accent: 'text-accent-700 dark:text-accent-300',
-  muted: 'text-gray-600 dark:text-gray-400'
-};
+  muted: 'text-gray-600 dark:text-gray-400',
+}
 ---
 
-<p class={`
+<p
+  class={`
   font-medium
   leading-relaxed
   mb-8
   ${sizeClasses[size]}
   ${alignment}
   ${colorClasses[color]}
   ${className}
-`}>
+`}
+>
   <slot />
-</p>
+</p>

src/components/ui/WideLayout.astro

@@ -1,14 +1,11 @@
 ---
 // WideLayout.astro - A reusable component for wider page layouts
 export interface Props {
-  class?: string;
-  maxWidth?: string;
+  class?: string
+  maxWidth?: string
 }
 
-const {
-  class: className = '',
-  maxWidth = '75rem'
-} = Astro.props;
+const { class: className = '', maxWidth = '75rem' } = Astro.props
 ---
 
 <div class={`wide-layout ${className}`} style={`--wide-max-width: ${maxWidth}`}>
@@ -37,4 +34,4 @@ const {
       padding: 0 1rem;
     }
   }
-</style>
+</style>