diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 70cb881..43e6616 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -1,6 +1,7 @@ import { defineConfig } from "astro/config"; import starlight from "@astrojs/starlight"; import starlightLinksValidatorPlugin from "starlight-links-validator"; +import starlightUtils from "@lorenzo_lewis/starlight-utils"; // https://astro.build/config export default defineConfig({ @@ -16,12 +17,16 @@ export default defineConfig({ label: "Docs", autogenerate: { directory: "/docs" }, }, + { + label: "Utilities", + autogenerate: { directory: "/utilities" }, + }, { label: "References", autogenerate: { directory: "/references" }, }, ], - plugins: [starlightLinksValidatorPlugin()], + plugins: [starlightLinksValidatorPlugin(), starlightUtils()], }), ], }); diff --git a/docs/src/content/docs/_quick-start.mdx b/docs/src/content/docs/_quick-start.mdx index e4595b8..026ef5d 100644 --- a/docs/src/content/docs/_quick-start.mdx +++ b/docs/src/content/docs/_quick-start.mdx @@ -27,6 +27,6 @@ import { PackageManagers } from "starlight-package-managers"; }); ``` -4. Go to the [Configuration Guide](/configuration) to continue setting up! ✨ +4. Go to the [Configuration Guide](/docs/configuration) to learn how to set up the different utilities ✨ diff --git a/docs/src/content/docs/configuration.md b/docs/src/content/docs/configuration.md deleted file mode 100644 index 9e50789..0000000 --- a/docs/src/content/docs/configuration.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Configuration -sidebar: - order: 2 ---- diff --git a/docs/src/content/docs/docs/recommended.mdx b/docs/src/content/docs/docs/recommended.mdx index 009ced1..f6d861b 100644 --- a/docs/src/content/docs/docs/recommended.mdx +++ b/docs/src/content/docs/docs/recommended.mdx @@ -1,3 +1,25 @@ --- -title: Recommended Plugins +title: Recommended Resources --- + +import { LinkCard, CardGrid } from "@astrojs/starlight/components"; + +## Plugins + +These are plugins not included in this utility but are fantastic to add to your Starlight site. + + + + + +--- + + diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 23b9893..e2275bd 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -1,10 +1,9 @@ --- title: 🧰 Starlight Utils -description: A collection of utilities to build on top of your 🌟 Starlight site. +description: Utilities to use with your 🌟 Starlight site tableOfContents: false -template: splash hero: - tagline: A collection of utilities to build on top of your 🌟 Starlight site. + tagline: Utilities to use with your 🌟 Starlight site image: file: ../../assets/houston.webp actions: @@ -14,14 +13,6 @@ hero: variant: primary --- -import { LinkCard, CardGrid } from "@astrojs/starlight/components"; - - - - - - - import QuickStart from "./_quick-start.mdx"; ## Quick Start diff --git a/docs/src/content/docs/references/index.mdx b/docs/src/content/docs/references/index.mdx index bd91424..257423a 100644 --- a/docs/src/content/docs/references/index.mdx +++ b/docs/src/content/docs/references/index.mdx @@ -1,5 +1,5 @@ --- -title: References +title: API Reference sidebar: order: 1 --- diff --git a/docs/src/content/docs/utilities/index.mdx b/docs/src/content/docs/utilities/index.mdx new file mode 100644 index 0000000..9f88d31 --- /dev/null +++ b/docs/src/content/docs/utilities/index.mdx @@ -0,0 +1,3 @@ +--- +title: List of Utilities +--- diff --git a/docs/src/content/docs/utilities/multi-sidebar.mdx b/docs/src/content/docs/utilities/multi-sidebar.mdx new file mode 100644 index 0000000..d51d6e5 --- /dev/null +++ b/docs/src/content/docs/utilities/multi-sidebar.mdx @@ -0,0 +1,43 @@ +--- +title: Multi-Sidebar +--- + +There are cases where having multiple sidebars for a Starlight site can be useful. [Starlight does not currently support this natively](https://github.com/withastro/starlight/discussions/959), but this utility gives a minimal implementation of this. + +## Demo + +import { Sidebar } from "@lorenzo_lewis/starlight-utils/components"; + +## Configuration + +See below for how to configure each of these actions. + +```ts {12-14} +// astro.config.mjs +import { defineConfig } from "astro/config"; +import starlight from "@astrojs/starlight"; +import starlightUtils from "@lorenzo_lewis/starlight-utils"; + +// https://astro.build/config +export default defineConfig({ + integrations: [ + starlight({ + plugins: [ + starlightUtils({ + multiSidebar: { + switcherStyle: "horizontalList", + }, + }), + ], + }), + ], +}); +``` + +## `switcherStyle` + +**Type:** `"dropdown" | "horizontalList"` + +**Default:** `"horizontalList"` + +Specifies which style should be used for the sidebar. diff --git a/packages/starlight-utils/README.md b/packages/starlight-utils/README.md index 030da8c..e1cdb16 100644 --- a/packages/starlight-utils/README.md +++ b/packages/starlight-utils/README.md @@ -1,5 +1,5 @@ # 🗄️ Starlight Utils -A collection of utilities to build on top of your 🌟 [Starlight](https://starlight.astro.build) site. +Utilities to use with your 🌟 [Starlight](https://starlight.astro.build) site. Visit the documentation for instructions on how to use: https://starlight-utils.pages.dev diff --git a/packages/starlight-utils/components/index.ts b/packages/starlight-utils/components/index.ts new file mode 100644 index 0000000..67e669f --- /dev/null +++ b/packages/starlight-utils/components/index.ts @@ -0,0 +1,3 @@ +import Sidebar from "../overrides/Sidebar.astro"; + +export { Sidebar }; diff --git a/packages/starlight-utils/config.ts b/packages/starlight-utils/config.ts index b029ae6..bf7feb6 100644 --- a/packages/starlight-utils/config.ts +++ b/packages/starlight-utils/config.ts @@ -2,9 +2,13 @@ import { AstroError } from "astro/errors"; import { z } from "astro/zod"; export const configSchema = z - .object({ switcherStyle: z.enum(["dropdown", "horizontalList"]) }) + .object({ + multiSidebar: z.object({ + switcherStyle: z.enum(["dropdown", "horizontalList"]), + }), + }) .optional() - .default({ switcherStyle: "horizontalList" }); + .default({ multiSidebar: { switcherStyle: "horizontalList" } }); export function validateConfig(userConfig: unknown): StarlightUtilsConfig { const config = configSchema.safeParse(userConfig); diff --git a/packages/starlight-utils/index.ts b/packages/starlight-utils/index.ts index e25b5fb..bca2ed8 100644 --- a/packages/starlight-utils/index.ts +++ b/packages/starlight-utils/index.ts @@ -7,13 +7,7 @@ function plugin(userConfig?: StarlightUtilsConfig): StarlightPlugin { return { name: "starlight-utils", hooks: { - setup({ config, updateConfig, addIntegration }) { - updateConfig({ - components: { - ...config.components, - Sidebar: "@lorenzo_lewis/starlight-utils/overrides/Sidebar.astro", - }, - }); + setup({ addIntegration }) { addIntegration(integration(multiSidebarConfig)); }, }, diff --git a/packages/starlight-utils/package.json b/packages/starlight-utils/package.json index cf72845..7055865 100644 --- a/packages/starlight-utils/package.json +++ b/packages/starlight-utils/package.json @@ -3,15 +3,13 @@ "author": "Lorenzo Lewis", "version": "0.0.1", "license": "MIT", - "description": "A collection of utilities to build on top of your 🌟 Starlight site.", + "description": "Utilities to use with your 🌟 Starlight site.", "type": "module", "exports": { ".": "./index.ts", - "./overrides/Sidebar.astro": "./overrides/Sidebar.astro" - }, - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" + "./components": "./components/index.ts" }, + "scripts": {}, "devDependencies": { "@astrojs/starlight": "^0.23.1", "astro": "^4.8.6"