Migrate docs to Vitepress (#1446)

Author: drwpow

docs/.gitignore

@@ -0,0 +1,2 @@
+.vitepress/cache
+.vitepress/dist

docs/.vitepress/config.ts

@@ -0,0 +1,81 @@
+import { defineConfig } from "vitepress";
+import packageJSON from "../../packages/openapi-typescript/package.json";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "OpenAPI TS",
+  description: "Consume OpenAPI 3.0 & 3.1 schemas in TypeScript",
+  cleanUrls: true,
+  /** @see https://vitepress.dev/reference/default-theme-config */
+  themeConfig: {
+    siteTitle: false,
+    logo: "/assets/openapi-ts.svg",
+    nav: [
+      {
+        text: "Versions",
+        items: [
+          { text: "7.x", link: "/introduction" },
+          { text: "6.x", link: "/6.x/introduction" },
+        ],
+      },
+    ],
+    sidebar: {
+      // 6.x docs
+      "/6.x/": [
+        {
+          text: "openapi-typescript (6.x)",
+          items: [
+            { text: "Introduction", link: "/6.x/introduction" },
+            { text: "CLI", link: "/6.x/cli" },
+            { text: "Node.js API", link: "/6.x/node" },
+            { text: "Advanced", link: "/6.x/advanced" },
+            { text: "About", link: "/6.x/about" },
+          ],
+        },
+        {
+          text: "openapi-fetch",
+          items: [
+            { text: "Introduction", link: "/openapi-fetch/" },
+            { text: "Examples", link: "/openapi-fetch/examples" },
+            { text: "API", link: "/openapi-fetch/api" },
+            { text: "About", link: "/openapi-fetch/about" },
+          ],
+        },
+      ],
+      // default (7.x) docs
+      "/": [
+        {
+          text: "openapi-typescript (7.x)",
+          items: [
+            { text: "Introduction", link: "/introduction" },
+            { text: "CLI", link: "/cli" },
+            { text: "Node.js API", link: "/node" },
+            { text: "Migrating from 6.x", link: "/migration-guide" },
+            { text: "Advanced", link: "/advanced" },
+            { text: "About", link: "/about" },
+          ],
+        },
+        {
+          text: "openapi-fetch",
+          items: [
+            { text: "Introduction", link: "/openapi-fetch/" },
+            { text: "Examples", link: "/openapi-fetch/examples" },
+            { text: "API", link: "/openapi-fetch/api" },
+            { text: "About", link: "/openapi-fetch/about" },
+          ],
+        },
+      ],
+    },
+    search: {
+      provider: "algolia",
+      options: {
+        appId: "NA92XVKBVS",
+        apiKey: "4f3ce9ca7edc3b83c209e6656ab29eb8",
+        indexName: "openapi-ts",
+      },
+    },
+    socialLinks: [
+      { icon: "github", link: "https://github.com/drwpow/openapi-typescript" },
+    ],
+  },
+});

docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from "vue";
+import type { Theme } from "vitepress";
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    });
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  },
+} satisfies Theme;

docs/.vitepress/theme/style.css

@@ -0,0 +1,157 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Fonts
+ */
+
+@font-face {
+  font-family: "Geist";
+  src: url("/assets/GeistVariableVF.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Geist Mono";
+  src: url("/assets/GeistMonoVariableVF.woff2") format("woff2");
+}
+
+:root {
+  --vp-font-family-mono: ui-monospace, "Geist Mono", SFMono-Regular, "SF Mono",
+    Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+}
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ *
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: oklch(0.6 0.22 260);
+  --vp-c-brand-2: oklch(0.4 0.2 260);
+  --vp-c-brand-3: oklch(0.5 0.2 260);
+  --vp-c-brand-soft: oklch(0.6 0.22 260/0.1);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    var(--vp-c-brand-1) 30%,
+    var(--vp-c-brand-2)
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    var(--vp-c-brand-1) 50%,
+    var(--vp-c-brand-2)
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}

docs/src/content/docs/v6/about.md renamed to docs/6.x/about.md

@@ -3,6 +3,13 @@ title: About
 description: Additional info about this project
 ---
 
+<script setup>
+  import { VPTeamMembers } from 'vitepress/theme';
+  import contributors from '../data/contributors.json';
+</script>
+
+# About openapi-typescript
+
 ## Used by
 
 - [**Bigcommerce**](https://github.com/bigcommerce/bigcommerce-api-node): Node SDK for the BigCommerce API
@@ -14,7 +21,8 @@ description: Additional info about this project
 - [**Lotus**](https://github.com/uselotus/lotus): open source pricing & packaging infra
 - [**Jitsu**](https://github.com/jitsucom/jitsu): modern, open source data ingestion / data pipelines
 - [**Medusa**](https://github.com/medusajs/medusa): building blocks for digital commerce
-- [**Nitro engine**](https://github.com/unjs/nitro): universal web server engine that powers Nuxt
+- [**Netlify**](https://netlify.com): the modern development platform
+- [**Nuxt**](https://github.com/unjs/nitro): The Intuitive Vue framework
 - [**Relevance AI**](https://github.com/RelevanceAI/relevance-js-sdk): build and deploy AI chains
 - [**Revolt**](https://github.com/revoltchat/api): open source user-first chat platform
 - [**Spacebar**](https://github.com/spacebarchat): a free, open source, self-hostable Discord-compatible chat/voice/video platform
@@ -24,12 +32,30 @@ description: Additional info about this project
 ## Project goals
 
 1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
-1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like <a href="https://www.typescriptlang.org/docs/handbook/enums.html" target="_blank" rel="noopener noreferrer">enums</a>).
-1. Don’t validate schemas; there are existing libraries for that like <a href="https://redocly.com/docs/cli/commands/lint/" target="_blank" rel="noopener noreferrer">Redocly</a>.
+1. Generated types should be statically-analyzable and runtime-free (with minor exceptions like [enums](https://www.typescriptlang.org/docs/handbook/enums.html).
+1. Don’t validate schemas; there are existing libraries for that like [Redocly](https://redocly.com/docs/cli/commands/lint/).
 1. Generated types should match your original schema as closely as possible, preserving original capitalization, etc.
 1. Typegen only needs Node.js to run (no Java, Python, etc.) and works in any environment.
 1. Support fetching OpenAPI schemas from files as well as local and remote servers.
 
+## Differences
+
+### vs. swagger-codegen
+
+openapi-typescript was created specifically to be a lighterweight, easier-to-use alternative to swagger-codegen that doesn’t require the Java runtime or running an OpenAPI server. Nor does it generate heavyweight clientside code. In fact, all the code openapi-typescript generates is **runtime free static types** for maximum performance and minimum client weight.
+
+### vs. openapi-typescript-codegen
+
+These 2 projects are unrelated. openapi-typescript-codegen is a Node.js alternative to the original swagger-codegen, but ends up being the same in practice. openapi-typescript has the same advantage of being **runtime free** whereas openapi-typescript-codegen can generate some pretty heavy bundles, up to `250 kB` or more depending on the schema complexity.
+
+### vs. tRPC
+
+[tRPC](https://trpc.io/) is an opinionated typesafe framework for both server and client. It demands both your server and client be written in tRPC (which means Node.js for the backend).
+
+If you fit into this usecase, it’s a great experience! But for everyone else, openapi-typescript (and openapi-fetch) is a more flexible, lower-level solution that can work for any technology choice (or even be incrementally-adopted without any cost).
+
 ## Contributors
 
 This library wouldn’t be possible without all these amazing contributors:
+
+<VPTeamMembers size="small" :members="contributors['openapi-typescript']" />

docs/src/content/docs/v6/advanced.md renamed to docs/6.x/advanced.md

@@ -3,6 +3,8 @@ title: Advanced
 description: Advanced usage as well as tips, tricks, and best practices
 ---
 
+# Advanced usage
+
 Advanced usage and various topics.
 
 ## Data fetching
@@ -12,9 +14,11 @@ Fetching data can be done simply and safely using an **automatically-typed fetch
 - [openapi-fetch](./openapi-fetch) (recommended)
 - [openapi-typescript-fetch](https://www.npmjs.com/package/openapi-typescript-fetch) by [@ajaishankar](https://github.com/ajaishankar)
 
-> ✨ **Tip**
->
-> A good fetch wrapper should **never use generics.** Generics require more typing and can hide errors!
+::: tip
+
+A good fetch wrapper should **never use generics.** Generics require more typing and can hide errors!
+
+:::
 
 ## Testing
 
@@ -34,8 +38,9 @@ Let’s say we want to write our mocks in the following object structure, so we
 
 Using our generated types we can then infer **the correct data shape** for any given path + HTTP method + status code. An example test would look like this:
 
-```ts
-// my-test.test.ts
+::: code-group
+
+```ts [my-test.test.ts]
 import { mockResponses } from "../test/utils";
 
 describe("My API test", () => {
@@ -71,15 +76,18 @@ describe("My API test", () => {
 });
 ```
 
+:::
+
 _Note: this example uses a vanilla `fetch()` function, but any fetch wrapper—including [openapi-fetch](/openapi-fetch)—could be dropped in instead without any changes._
 
 And the magic that produces this would live in a `test/utils.ts` file that can be copy + pasted where desired (hidden for simplicity):
 
 <details>
 <summary>📄 <strong>test/utils.ts</strong></summary>
 
+::: code-group [test/utils.ts]
+
 ```ts
-// test/utils.ts
 import { paths } from "./api/v1/my-schema"; // generated by openapi-typescript
 
 // Settings
@@ -159,7 +167,13 @@ export function findPath(
 }
 ```
 
-> **Additional Explanation** That code is quite above is quite a doozy! For the most part, it’s a lot of implementation detail you can ignore. The `mockResponses(…)` function signature is where all the important magic happens—you’ll notice a direct link between this structure and our design. From there, the rest of the code is just making the runtime work as expected.
+:::
+
+::: info Additional Explanation
+
+That code is quite above is quite a doozy! For the most part, it’s a lot of implementation detail you can ignore. The `mockResponses(…)` function signature is where all the important magic happens—you’ll notice a direct link between this structure and our design. From there, the rest of the code is just making the runtime work as expected.
+
+:::
 
 ```ts
 export function mockResponses(responses: {
@@ -372,7 +386,7 @@ prefixItems:
 
 ### Use `$defs` only in object types
 
-<a href="https://json-schema.org/understanding-json-schema/structuring.html#defs" target="_blank" rel="noopener noreferrer">JSONSchema $defs</a> can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:
+[JSONSchema $defs](https://json-schema.org/understanding-json-schema/structuring.html#defs) can be used to provide sub-schema definitions anywhere. However, these won’t always convert cleanly to TypeScript. For example, this works:
 
 ```yaml
 components: