Merge pull request #2621 from hey-api/docs/nav-core

docs: simplify navigation

Author: mrlubos

.changeset/brown-paws-design.md

@@ -2,4 +2,10 @@
 '@hey-api/openapi-ts': minor
 ---
 
-feat: add symbol api
+feat: Symbol API
+
+### Symbol API
+
+This release adds the Symbol API, which significantly reduces the risk of naming collisions. While the generated output should only include formatting changes, this feature introduces breaking changes to the Plugin API that affect custom plugins.
+
+We will update the [custom plugin guide](https://heyapi.dev/openapi-ts/plugins/custom) once the Plugin API becomes more stable.

.changeset/cuddly-bears-deny.md

@@ -2,4 +2,4 @@
 '@hey-api/codegen-core': minor
 ---
 
-feat: expand symbol api
+feat: expand Symbol API

.changeset/thirty-shoes-end.md

@@ -2,4 +2,8 @@
 '@hey-api/openapi-ts': minor
 ---
 
-feat(pinia-colada): remove groupByTag option
+feat(pinia-colada): remove `groupByTag` option
+
+### Removed `groupByTag` Pinia Colada option
+
+This option has been removed to provide a more consistent API across plugins. We plan to bring it back in a future release.

docs/.vitepress/config/en.ts

@@ -48,6 +48,10 @@ export default defineConfig({
             link: '/openapi-ts/configuration',
             text: 'Configuration',
           },
+          {
+            link: '/openapi-ts/output',
+            text: 'Output',
+          },
         ],
         text: 'Introduction',
       },
@@ -57,35 +61,24 @@ export default defineConfig({
             collapsed: true,
             items: [
               {
-                link: '/openapi-ts/output/typescript',
+                link: '/openapi-ts/plugins/typescript',
                 text: 'TypeScript',
               },
               {
-                link: '/openapi-ts/output/sdk',
+                link: '/openapi-ts/plugins/sdk',
                 text: 'SDK',
               },
               {
-                link: '/openapi-ts/output/client',
-                text: 'Client',
-              },
-              {
-                link: '/openapi-ts/output/json-schema',
-                text: 'JSON Schema',
+                link: '/openapi-ts/plugins/transformers',
+                text: 'Transformers',
               },
-            ],
-            link: '/openapi-ts/output',
-            text: 'Output',
-          },
-          {
-            collapsed: true,
-            items: [
               {
-                link: '/openapi-ts/plugins/custom',
-                text: 'Custom Plugin',
+                link: '/openapi-ts/plugins/schemas',
+                text: 'Schemas',
               },
             ],
-            link: '/openapi-ts/plugins',
-            text: 'Plugins',
+            link: '/openapi-ts/core',
+            text: 'Core',
           },
           {
             collapsed: true,
@@ -114,10 +107,6 @@ export default defineConfig({
                 link: '/openapi-ts/clients/effect',
                 text: 'Effect <span data-soon>soon</span>',
               },
-              {
-                link: '/openapi-ts/clients/custom',
-                text: 'Custom Client',
-              },
               {
                 link: '/openapi-ts/clients/legacy',
                 text: 'Legacy',
@@ -165,10 +154,6 @@ export default defineConfig({
             link: '/openapi-ts/validators',
             text: 'Validators',
           },
-          {
-            link: '/openapi-ts/transformers',
-            text: 'Transformers',
-          },
           {
             collapsed: true,
             items: [
@@ -258,6 +243,20 @@ export default defineConfig({
             link: '/openapi-ts/web-frameworks',
             text: 'Web Frameworks',
           },
+          {
+            collapsed: true,
+            items: [
+              {
+                link: '/openapi-ts/plugins/custom',
+                text: 'Plugin',
+              },
+              {
+                link: '/openapi-ts/clients/custom',
+                text: 'Client',
+              },
+            ],
+            text: 'Custom',
+          },
         ],
         text: 'Guides and Concepts',
       },

docs/index.md

@@ -3,7 +3,7 @@ layout: home
 
 hero:
   name: One OpenAPI spec.<br/>Infinite outputs.
-  tagline: Codegen for JavaScript/TypeScript projects. Trusted over 2,000,000 times each month to generate reliable API clients and SDKs.
+  tagline: Codegen for JavaScript/TypeScript projects. Trusted over 2,500,000 times each month to generate reliable API clients and SDKs.
   actions:
     - link: /openapi-ts/get-started
       text: Get Started

docs/openapi-ts/core.md

@@ -0,0 +1,22 @@
+---
+title: Core Plugins
+description: Learn about the core plugins provided by Hey API.
+---
+
+# Core
+
+Apart from being responsible for the default output, core plugins are the foundation for other plugins. Instead of creating their own primitives, other plugins can reuse the artifacts from core plugins. This results in a smaller output size and a better user experience.
+
+## Options
+
+Hey API provides the following core plugins.
+
+- [TypeScript](/openapi-ts/plugins/typescript)
+- [SDK](/openapi-ts/plugins/sdk)
+- [Transformers](/openapi-ts/plugins/transformers)
+- [Schemas](/openapi-ts/plugins/schemas)
+
+Need another core plugin? Let us know your interest by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
+
+<!--@include: ../partials/examples.md-->
+<!--@include: ../partials/sponsors.md-->

docs/openapi-ts/get-started.md

@@ -9,7 +9,7 @@ import { embedProject } from '../embed'
 
 # Get Started
 
-[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted over 2,000,000 times each month to generate reliable API clients and SDKs. The code is [MIT-licensed](/openapi-ts/license) and free to use. Discover available features below or view our [roadmap](https://github.com/orgs/hey-api/discussions/1495) to learn what's coming next.
+[@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts) is an OpenAPI to TypeScript codegen trusted over 2,500,000 times each month to generate reliable API clients and SDKs. The code is [MIT-licensed](/openapi-ts/license) and free to use. Discover available features below or view our [roadmap](https://github.com/orgs/hey-api/discussions/1495) to learn what's coming next.
 
 ### Demo
 

docs/openapi-ts/migrating.md

@@ -7,9 +7,21 @@ description: Migrating to @hey-api/openapi-ts.
 
 While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
 
+## v0.83.0
+
+### Symbol API
+
+This release adds the Symbol API, which significantly reduces the risk of naming collisions. While the generated output should only include formatting changes, this feature introduces breaking changes to the Plugin API that affect custom plugins.
+
+We will update the [custom plugin guide](/openapi-ts/plugins/custom) once the Plugin API becomes more stable.
+
+### Removed `groupByTag` Pinia Colada option
+
+This option has been removed to provide a more consistent API across plugins. We plan to bring it back in a future release.
+
 ## v0.82.0
 
-### Added Hooks API
+### Hooks API
 
 This release adds the [Hooks API](/openapi-ts/configuration/parser#hooks), giving you granular control over which operations generate queries and mutations. As a result, we tightened the previous behavior and POST operations no longer generate queries by default. To preserve the old behavior, add a custom matcher.
 

docs/openapi-ts/output.md

@@ -5,11 +5,7 @@ description: Learn about files generated with @hey-api/openapi-ts.
 
 # Output
 
-Learn about files generated with `@hey-api/openapi-ts`.
-
-::: tip
-Your actual output depends on your Hey API configuration. It may contain a different number of files and their contents might differ.
-:::
+Every generated file in your output folder is created by a plugin. This page describes the default output, but similar logic applies to all plugins.
 
 ## Overview
 
@@ -30,13 +26,41 @@ my-app/
 └── package.json
 ```
 
-Each file is an artifact generated by a Hey API plugin. This is the default output, we will cover customizing it in this section. These files also form the base for third-party plugins.
+Your actual output depends on your Hey API configuration. It may contain a different number of files and their contents might differ.
 
 Let's go through each file in the `src/client` folder and explain what it looks like, what it does, and how to use it.
 
-## Index
+## Client
+
+`client.gen.ts` is generated by [client plugins](/openapi-ts/clients). If you choose to generate SDKs (enabled by default), we use the Fetch client unless specified otherwise.
+
+::: code-group
+
+```ts [client.gen.ts]
+import { createClient, createConfig } from './client';
+
+export const client = createClient(createConfig());
+```
+
+:::
+
+The contents of this file are consumed by SDKs, but you can also import `client` in your application to perform additional configuration or send manual requests.
+
+### Bundle
+
+Client plugins provide their bundles inside `client` and `core` folders. The contents of these folders don't depend on the provided input. Everything inside these folders serves as a scaffolding so the generated code can make HTTP requests.
+
+## TypeScript
+
+You can learn more on the [TypeScript](/openapi-ts/plugins/typescript) page.
+
+## SDK
+
+You can learn more on the [SDK](/openapi-ts/plugins/sdk) page.
+
+## Barrel File
 
-`index.ts` is the only file not generated by a specific plugin. It's meant for convenience and by default, it re-exports every artifact generated by default plugins (TypeScript and SDK).
+`index.ts` is not generated by any specific plugin. It's meant for convenience and by default, it re-exports every artifact generated by default plugins (TypeScript and SDK).
 
 ::: code-group