Merge pull request #36 from HiDeoo/hd-docs-improvements

HiDeoo · Jun 24, 2024 · 939fbcf · 939fbcf
2 parents ae6de0d + 1724158
commit 939fbcf
Show file tree

Hide file tree

Showing 17 changed files with 1,251 additions and 951 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -15,7 +15,7 @@
 
 ## Docs
 
-Run the docs locally using your favorite package manager, e.g. with [pnpm](https://pnpm.io):
+Run the docs locally using [pnpm](https://pnpm.io):
 
 ```shell
 pnpm run dev

diff --git a/docs/astro.config.ts b/docs/astro.config.ts
@@ -62,6 +62,13 @@ export default defineConfig({
             { label: 'Configuration', link: '/configuration/' },
           ],
         },
+        {
+          label: 'Resources',
+          items: [
+            { label: 'Showcase', link: '/resources/showcase/' },
+            { label: 'Plugins and Tools', link: '/resources/starlight/' },
+          ],
+        },
         {
           label: 'Demo',
           items: openAPISidebarGroups,

diff --git a/docs/package.json b/docs/package.json
@@ -14,11 +14,11 @@
     "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
   },
   "dependencies": {
-    "@astrojs/starlight": "0.19.0",
-    "astro": "4.4.0",
-    "sharp": "0.33.2",
-    "starlight-openapi": "workspace:*",
-    "starlight-package-managers": "0.3.0"
+    "@astrojs/starlight": "0.24.4",
+    "@hideoo/starlight-plugins-docs-components": "^0.2.2",
+    "astro": "4.11.1",
+    "sharp": "0.32.6",
+    "starlight-openapi": "workspace:*"
   },
   "engines": {
     "node": ">=18.14.1"

diff --git a/docs/src/assets/showcase/classchartsapi.github.io.png b/docs/src/assets/showcase/classchartsapi.github.io.png
diff --git a/docs/src/assets/showcase/docs.garajonai.com.png b/docs/src/assets/showcase/docs.garajonai.com.png
diff --git a/docs/src/assets/showcase/docs.taiko.xyz.png b/docs/src/assets/showcase/docs.taiko.xyz.png
diff --git a/docs/src/assets/showcase/fxhu.kripod.dev.png b/docs/src/assets/showcase/fxhu.kripod.dev.png
diff --git a/docs/src/assets/showcase/openpayments.dev.png b/docs/src/assets/showcase/openpayments.dev.png
diff --git a/docs/src/assets/showcase/openpodcastapi.org.png b/docs/src/assets/showcase/openpodcastapi.org.png
diff --git a/docs/src/components/PackageManagers.astro b/docs/src/components/PackageManagers.astro
diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
@@ -3,8 +3,6 @@ title: Getting Started
 description: Learn how to generate documentation from OpenAPI/Swagger specifications using the Starlight OpenAPI plugin.
 ---
 
-import PackageManagers from '../../components/PackageManagers.astro'
-
 A [Starlight](https://starlight.astro.build) plugin to generate documentation from OpenAPI/Swagger specifications.
 
 - Support for [Swagger 2.0](https://swagger.io/specification/v2/), [OpenAPI 3.0](https://swagger.io/specification/v3/) and [OpenAPI 3.1](https://swagger.io/specification/) specifications.
@@ -16,48 +14,56 @@ A [Starlight](https://starlight.astro.build) plugin to generate documentation fr
 You will need to have a Starlight website set up.
 If you don't have one yet, you can follow the ["Getting Started"](https://starlight.astro.build/getting-started) guide in the Starlight docs to create one.
 
-## Install the plugin
-
-Starlight OpenAPI is a Starlight [plugin](https://starlight.astro.build/reference/plugins/).
-Install it using your favorite package manager:
-
-<PackageManagers pkg="starlight-openapi" />
-
-## Configure the plugin
-
-The Starlight OpenAPI plugin can be configured in your Starlight [configuration](https://starlight.astro.build/reference/configuration/#plugins) in the `astro.config.mjs` file.
-
-```diff lang="js"
-// astro.config.mjs
-import starlight from '@astrojs/starlight'
-import { defineConfig } from 'astro/config'
-+import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'
-
-export default defineConfig({
-  integrations: [
-    starlight({
-+      plugins: [
-+        // Generate the OpenAPI documentation pages.
-+        starlightOpenAPI([
-+          {
-+           base: 'api',
-+           label: 'My API',
-+           schema: '../schemas/api-schema.yaml',
-+          },
-+        ]),
-+      ],
-      sidebar: [
-        {
-          label: 'Guides',
-          items: [{ label: 'Example Guide', link: '/guides/example/' }],
-        },
-+        // Add the generated sidebar group to the sidebar.
-+        ...openAPISidebarGroups,
-      ],
-      title: 'My Docs',
-    }),
-  ],
-})
-```
+## Installation
+
+import { Steps } from '@astrojs/starlight/components'
+import { PackageManagers } from '@hideoo/starlight-plugins-docs-components'
+
+<Steps>
+
+1. Starlight OpenAPI is a Starlight [plugin](https://starlight.astro.build/reference/plugins/). Install it using your favorite package manager:
+
+   <PackageManagers pkg="starlight-openapi" />
+
+2. Configure the plugin in your Starlight [configuration](https://starlight.astro.build/reference/configuration/#plugins) in the `astro.config.mjs` file.
+
+   The following example shows how to specify a schema file and add the generated sidebar group to the sidebar:
+
+   ```diff lang="js"
+   // astro.config.mjs
+   import starlight from '@astrojs/starlight'
+   import { defineConfig } from 'astro/config'
+   +import starlightOpenAPI, { openAPISidebarGroups } from 'starlight-openapi'
+
+   export default defineConfig({
+     integrations: [
+       starlight({
+   +      plugins: [
+   +        // Generate the OpenAPI documentation pages.
+   +        starlightOpenAPI([
+   +          {
+   +           base: 'api',
+   +           label: 'My API',
+   +           schema: '../schemas/api-schema.yaml',
+   +          },
+   +        ]),
+   +      ],
+         sidebar: [
+           {
+             label: 'Guides',
+             items: [{ label: 'Example Guide', link: '/guides/example/' }],
+           },
+   +        // Add the generated sidebar group to the sidebar.
+   +        ...openAPISidebarGroups,
+         ],
+         title: 'My Docs',
+       }),
+     ],
+   })
+   ```
+
+3. [Start the development server](https://starlight.astro.build/getting-started/#start-the-development-server) to preview the generated documentation.
+
+</Steps>
 
 The Starlight OpenAPI plugin behavior can be tweaked using various [configuration options](/configuration).
diff --git a/docs/src/content/docs/resources/showcase.mdx b/docs/src/content/docs/resources/showcase.mdx
@@ -0,0 +1,52 @@
+---
+title: Showcase
+description: Discover Starlight project using the Starlight OpenAPI plugin.
+---
+
+import { ShowcaseIntro, Showcase } from '@hideoo/starlight-plugins-docs-components'
+
+<ShowcaseIntro
+  cta="Have you built a documentation using Starlight OpenAPI?"
+  href="https://github.com/HiDeoo/starlight-openapi/edit/main/docs/src/content/docs/resources/showcase.mdx"
+/>
+
+## Sites
+
+Starlight OpenAPI is already being used in production. These are some of the sites around the web:
+
+<Showcase
+  entries={[
+    {
+      thumbnail: import('../../../assets/showcase/openpayments.dev.png'),
+      href: 'https://openpayments.dev/',
+      title: 'Open Payments',
+    },
+    {
+      thumbnail: import('../../../assets/showcase/classchartsapi.github.io.png'),
+      href: 'https://classchartsapi.github.io/api-docs/',
+      title: 'ClassCharts API',
+    },
+    {
+      thumbnail: import('../../../assets/showcase/openpodcastapi.org.png'),
+      href: 'https://openpodcastapi.org/',
+      title: 'Open Podcast API',
+    },
+    {
+      thumbnail: import('../../../assets/showcase/docs.garajonai.com.png'),
+      href: 'https://docs.garajonai.com/',
+      title: 'GarajonAI',
+    },
+    {
+      thumbnail: import('../../../assets/showcase/fxhu.kripod.dev.png'),
+      href: 'https://fxhu.kripod.dev/',
+      title: 'FXHU',
+    },
+    {
+      thumbnail: import('../../../assets/showcase/docs.taiko.xyz.png'),
+      href: 'https://docs.taiko.xyz/start-here/getting-started',
+      title: 'Taiko',
+    },
+  ]}
+/>
+
+See all the [public project repos using Starlight on GitHub](https://github.com/hideoo/starlight-openapi/network/dependents).
diff --git a/docs/src/content/docs/resources/starlight.mdx b/docs/src/content/docs/resources/starlight.mdx
@@ -0,0 +1,20 @@
+---
+title: Starlight Plugins and Tools
+description: Discover other Starlight plugins, components and tools developed by HiDeoo.
+---
+
+import { ResourcesIntro, Resources } from '@hideoo/starlight-plugins-docs-components'
+
+<ResourcesIntro />
+
+## Plugins
+
+<Resources type="plugins" />
+
+## Components
+
+<Resources type="components" />
+
+## Tools
+
+<Resources type="tools" />
diff --git a/package.json b/package.json
@@ -14,7 +14,7 @@
     "@hideoo/eslint-config": "3.0.0",
     "@hideoo/prettier-config": "2.0.0",
     "@hideoo/tsconfig": "2.0.1",
-    "astro": "4.4.0",
+    "astro": "4.11.1",
     "eslint": "8.56.0",
     "husky": "8.0.3",
     "lint-staged": "14.0.1",

diff --git a/packages/starlight-openapi/README.md b/packages/starlight-openapi/README.md
@@ -20,7 +20,7 @@
 
 ## Getting Started
 
-Want to get started immediately? Check out the [getting started guide](https://starlight-openapi.vercel.app/guides/getting-started/) or a [live demo](https://starlight-openapi.vercel.app/api/petstore/operations/addpet/).
+Want to get started immediately? Check out the [getting started guide](https://starlight-openapi.vercel.app/guides/getting-started/) or check out the [demo](https://starlight-openapi.vercel.app/api/petstore/operations/addpet/) to see the plugin in action.
 
 ## Features
 

diff --git a/packages/starlight-openapi/package.json b/packages/starlight-openapi/package.json
@@ -19,10 +19,10 @@
     "github-slugger": "2.0.0"
   },
   "devDependencies": {
-    "@astrojs/starlight": "0.19.0",
+    "@astrojs/starlight": "0.24.4",
     "@playwright/test": "1.36.2",
     "@types/node": "18.17.3",
-    "astro": "4.4.0",
+    "astro": "4.11.1",
     "openapi-types": "12.1.3"
   },
   "peerDependencies": {