docs: v3 docs structure

docusaurus.config.js

@@ -44,6 +44,10 @@ const config = {
                             label: '1.x',
                             banner: 'none',
                         },
+                        '3.x': {
+                            label: '3.0 Alpha',
+                            banner: 'none',
+                        },
                     },
                 },
                 blog: false,

package.json

@@ -22,8 +22,10 @@
         "@docusaurus/theme-mermaid": "3.4.0",
         "@giscus/react": "^2.4.0",
         "@mdx-js/react": "^3.0.1",
+        "@stackblitz/sdk": "^1.11.0",
         "autoprefixer": "^10.4.13",
         "clsx": "^1.2.1",
+        "is-mobile": "^5.0.0",
         "postcss": "^8.4.21",
         "prism-react-renderer": "^2.3.1",
         "prism-svelte": "^0.5.0",

src/components/GithubCodeBlock.tsx

@@ -0,0 +1,40 @@
+import CodeBlock from '@theme/CodeBlock';
+import { useEffect, useState } from 'react';
+
+interface GithubCodeBlockProps {
+    repoPath: string;
+    file: string;
+}
+
+const GithubCodeBlock: React.FC<GithubCodeBlockProps> = ({ repoPath, file }) => {
+    const [code, setCode] = useState<string>('Loading...');
+
+    useEffect(() => {
+        (async function () {
+            const response = await fetch(`https://cdn.jsdelivr.net/gh/${repoPath}/${file}`);
+            if (!response.ok) {
+                setCode(`Unable to load "${repoPath}/${file}"`);
+                return;
+            }
+            const text = await response.text();
+            setCode(text);
+        })();
+    }, [repoPath, file]);
+
+    const getLanguage = (file: string): string => {
+        if (file.endsWith('.ts')) {
+            return 'typescript';
+        } else if (file.endsWith('.zmodel')) {
+            return 'zmodel';
+        } else {
+            return 'plaintext';
+        }
+    };
+    return (
+        <CodeBlock language={getLanguage(file)} title={file}>
+            {code}
+        </CodeBlock>
+    );
+};
+
+export default GithubCodeBlock;

src/components/StackBlitzEmbed.tsx

@@ -0,0 +1,26 @@
+import React, { useEffect, useRef } from 'react';
+import sdk from '@stackblitz/sdk';
+
+interface StackBlitzEmbedProps {
+    projectId: string;
+    height?: string;
+}
+
+const StackBlitzEmbed: React.FC<StackBlitzEmbedProps> = ({ projectId, height = '600px' }) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    useEffect(() => {
+        if (containerRef.current) {
+            sdk.embedProjectId(containerRef.current, projectId, {
+                openFile: 'main.ts',
+                height,
+                view: 'editor',
+                forceEmbedLayout: true,
+            });
+        }
+    }, [projectId, height]);
+
+    return <div ref={containerRef} style={{ width: '100%', height }} />;
+};
+
+export default StackBlitzEmbed;

src/components/StackBlitzGithubEmbed.tsx

@@ -0,0 +1,84 @@
+import sdk from '@stackblitz/sdk';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+import mobile from 'is-mobile';
+import React, { useEffect, useRef } from 'react';
+import GithubCodeBlock from './GithubCodeBlock';
+
+interface StackBlitzGithubEmbedProps {
+    repoPath: string;
+    height?: string;
+    openFile?: string;
+    plainCodeFiles?: string[];
+    startScript?: string;
+    clickToLoad?: boolean;
+}
+
+const StackBlitzGithubEmbed: React.FC<StackBlitzGithubEmbedProps> = ({
+    repoPath,
+    height = '600px',
+    openFile = 'main.ts',
+    plainCodeFiles = undefined,
+    clickToLoad = false,
+    startScript,
+}) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+
+    const options = {
+        openFile,
+        height,
+        view: 'editor',
+        startScript,
+        clickToLoad,
+    } as const;
+
+    if (!plainCodeFiles) {
+        plainCodeFiles = [openFile];
+    }
+
+    useEffect(() => {
+        if (containerRef.current) {
+            setTimeout(() => {
+                // docusaurus seems to recreate the tab after mounting, give it a
+                // chance to complete
+                sdk.embedGithubProject(containerRef.current, repoPath, options);
+            }, 0);
+        }
+    }, [repoPath, height, containerRef]);
+
+    const PlainCode = () => (
+        <>
+            {plainCodeFiles.map((file) => (
+                <GithubCodeBlock key={file} repoPath={repoPath} file={file} />
+            ))}
+        </>
+    );
+
+    if (mobile()) {
+        return <PlainCode />;
+    } else {
+        return (
+            <>
+                <Tabs groupId="interactive-sample">
+                    <TabItem value="interactive" label="Interactive Sample" default>
+                        <div className="italic text-sm mb-1">
+                            Click{' '}
+                            <a href="#" onClick={() => sdk.openGithubProject(repoPath, options)}>
+                                here
+                            </a>{' '}
+                            to pop out if the embed doesn't load an interactive terminal.
+                        </div>
+                        <div ref={containerRef} style={{ width: '100%', height }} />
+                    </TabItem>
+                    <TabItem value="static" label="Plain Code">
+                        <PlainCode />
+                    </TabItem>
+                </Tabs>
+
+                <div></div>
+            </>
+        );
+    }
+};
+
+export default StackBlitzGithubEmbed;

versioned_docs/version-3.x/_components/PackageExec.tsx

@@ -0,0 +1,28 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+    command: string;
+}
+
+const pkgManagers = [
+    { name: 'npm', command: 'npx' },
+    { name: 'pnpm', command: 'pnpm' },
+    { name: 'bun', command: 'bunx' },
+    { name: 'yarn', command: 'npx' },
+];
+
+const PackageInstall = ({ command }: Props) => {
+    return (
+        <Tabs>
+            {pkgManagers.map((pkg) => (
+                <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
+                    <CodeBlock language="bash">{`${pkg.command} ${command}`}</CodeBlock>
+                </TabItem>
+            ))}
+        </Tabs>
+    );
+};
+
+export default PackageInstall;

versioned_docs/version-3.x/_components/PackageInstall.tsx

@@ -0,0 +1,33 @@
+import CodeBlock from '@theme/CodeBlock';
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+interface Props {
+    devDependencies: string[];
+    dependencies: string[];
+}
+
+const pkgManagers = [
+    { name: 'npm', command: 'npm install', dev: '--save-dev' },
+    { name: 'pnpm', command: 'pnpm add', dev: '--save-dev' },
+    { name: 'bun', command: 'bun add', dev: '--dev' },
+    { name: 'yarn', command: 'yarn add', dev: '--dev' },
+];
+
+const PackageInstall = ({ devDependencies, dependencies }: Props) => {
+    return (
+        <Tabs>
+            {pkgManagers.map((pkg) => (
+                <TabItem key={pkg.name} value={pkg.name} label={pkg.name}>
+                    <CodeBlock language="bash">
+                        {`${devDependencies?.length ? `${pkg.command} ${pkg.dev} ${devDependencies.join(' ')}\n` : ''}${
+                            dependencies?.length ? `${pkg.command} ${dependencies.join(' ')}` : ''
+                        }`}
+                    </CodeBlock>
+                </TabItem>
+            ))}
+        </Tabs>
+    );
+};
+
+export default PackageInstall;

versioned_docs/version-3.x/_components/ZModelVsPSL.tsx

@@ -0,0 +1,16 @@
+import React, { FC } from 'react';
+import Admonition from '@theme/Admonition';
+
+interface ZModelVsPSLProps {
+    children: React.ReactNode;
+}
+
+const ZModelVsPSL: FC<ZModelVsPSLProps> = ({ children }) => {
+    return (
+        <Admonition type="info" title="🔋 ZModel vs Prisma Schema">
+            {children}
+        </Admonition>
+    );
+};
+
+export default ZModelVsPSL;

versioned_docs/version-3.x/_components/ZenStackVsPrisma.tsx

@@ -0,0 +1,16 @@
+import React, { FC } from 'react';
+import Admonition from '@theme/Admonition';
+
+interface ZenStackVsPrismaProps {
+    children: React.ReactNode;
+}
+
+const ZenStackVsPrisma: FC<ZenStackVsPrismaProps> = ({ children }) => {
+    return (
+        <Admonition type="info" title="🔋 ZenStack vs Prisma">
+            {children}
+        </Admonition>
+    );
+};
+
+export default ZenStackVsPrisma;

versioned_docs/version-3.x/_components/_zmodel-starter.md

@@ -0,0 +1,23 @@
+  ```zmodel
+  datasource db {
+    provider = 'sqlite'
+    url = "file:./dev.db"
+  }
+
+  model User {
+    id       String @id @default(cuid())
+    email    String @unique
+    posts    Post[]
+  }
+
+  model Post {
+    id        String   @id @default(cuid())
+    createdAt DateTime @default(now())
+    updatedAt DateTime @updatedAt
+    title     String
+    content   String
+    published Boolean  @default(false)
+    author    User     @relation(fields: [authorId], references: [id])
+    authorId  String
+  }
+  ```

versioned_docs/version-3.x/faq.md

@@ -0,0 +1,14 @@
+---
+description: ZenStack FAQ.
+
+slug: /faq
+sidebar_label: FAQ
+sidebar_position: 100
+---
+
+# 🙋🏻 FAQ
+
+## What databases are supported?
+
+Currently only SQLite and PostgreSQL are supported. MySQL will be added in the future. There's no plan to support other relational databases or NoSQL databases.
+

versioned_docs/version-3.x/migration/_category_.yml

@@ -0,0 +1,4 @@
+position: 4
+label: Migration
+collapsible: true
+collapsed: true

versioned_docs/version-3.x/migration/index.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 1
+description: ZenStack migration overview
+---
+
+# Overview

versioned_docs/version-3.x/modeling/_category_.yml

@@ -0,0 +1,4 @@
+position: 2
+label: Data Modeling
+collapsible: true
+collapsed: true