feat: customize docs

florian-lefebvre · Feb 4, 2024 · 61315c5 · 61315c5
1 parent a59be59
commit 61315c5
Show file tree

Hide file tree

Showing 5 changed files with 138 additions and 35 deletions.
diff --git a/docs/astro.config.ts b/docs/astro.config.ts
@@ -1,5 +1,6 @@
 import starlight from "@astrojs/starlight";
 import { defineConfig } from "astro/config";
+import { version } from "../package/package.json";
 
 const badge = (type: "new" | "updated" | "soon") => ({
 	variant: {
@@ -32,6 +33,26 @@ export default defineConfig({
 				baseUrl:
 					"https://github.com/florian-lefebvre/astro-integration-kit/edit/main/docs/",
 			},
+			customCss: ["./src/styles/main.css"],
+			head: [
+				{
+					tag: "link",
+					attrs: {
+						rel: "preconnect",
+						href: "https://rsms.me/",
+					},
+				},
+				{
+					tag: "link",
+					attrs: {
+						rel: "stylesheet",
+						href: "https://rsms.me/inter/inter.css",
+					},
+				},
+			],
+			expressiveCode: {
+				themes: ["one-dark-pro", "starlight-light"]
+			},
 			sidebar: [
 				{
 					label: "Getting started",
@@ -59,10 +80,6 @@ export default defineConfig({
 				{
 					label: "Core",
 					items: [
-						{
-							label: "createResolver",
-							link: "/core/create-resolver/",
-						},
 						{
 							label: "defineIntegration",
 							link: "/core/define-integration/",
@@ -73,6 +90,10 @@ export default defineConfig({
 							link: "/core/define-options/",
 							badge: badge("new"),
 						},
+						{
+							label: "createResolver",
+							link: "/core/create-resolver/",
+						},
 						{
 							label: "definePlugin",
 							link: "/core/define-plugin/",
@@ -102,7 +123,7 @@ export default defineConfig({
 							badge: badge("updated"),
 						},
 						{
-							label: "watchIntegration",
+							label: "watchIntegration (HMR)",
 							link: "/utilities/watch-integration/",
 						},
 					],
@@ -122,6 +143,20 @@ export default defineConfig({
 						},
 					],
 				},
+				{
+					label: `v${version} changelog`,
+					link: `https://github.com/florian-lefebvre/astro-integration-kit/blob/main/package/CHANGELOG.md#${version.replaceAll(
+						".",
+						"",
+					)}`,
+					attrs: {
+						target: "_blank",
+					},
+					badge: {
+						variant: "note",
+						text: "Latest",
+					},
+				},
 			],
 			lastUpdated: true,
 		}),

diff --git a/docs/src/content/docs/core/create-resolver.mdx b/docs/src/content/docs/core/create-resolver.mdx
@@ -5,6 +5,11 @@ description: Allows resolving paths relatively to the integration folder easily.
 
 `createResolver` allows you to resolve paths relatively to the integration folder easily. For example:
 
+- quick snippet (overview)
+- why it's important / what it allows
+- why should you only pass `import.meta.url`
+- where to call it
+
 ```ts title="integration/index.ts"
 import type { AstroIntegration } from "astro";
 import { createResolver } from "astro-integration-kit";

diff --git a/docs/src/content/docs/core/define-integration.mdx b/docs/src/content/docs/core/define-integration.mdx
@@ -5,18 +5,22 @@ description: Makes creating integrations easier, and adds a few goodies!
 
 `defineIntegration` makes creating integrations easier, and adds a few goodies!
 
-:::caution
-`defineIntegration` is required to use **extended hooks**.
-:::
-
 ```ts title="my-integration/index.ts" "defineIntegration"
-import { createResolver, defineIntegration } from "astro-integration-kit";
+import {
+    createResolver,
+    defineIntegration,
+    defineOptions,
+} from "astro-integration-kit";
+import { corePlugins } from "astro-integration-kit/plugins";
+
+type Options = {
+    foo?: string | undefined;
+}
 
 export default defineIntegration<{ foo?: string }>({
     name: "my-integration",
-    defaults: {
-        foo: "bar"
-    },
+    options: defineOptions<Options>({ foo: "bar" }),
+    plugins: [...corePlugins],
     setup({ options }) {
         const { resolve } = createResolver(import.meta.url);
 
@@ -31,31 +35,26 @@ export default defineIntegration<{ foo?: string }>({
 
 ## Features
 
-### Options
+### Defining an integration
 
-`defineIntegration` accepts a generic that will properly type the integration options.
+- basic usage
+- never pass generics directly
+- link to guide
 
-### Defaults
+### Handling options and defaults
 
-The `defaults` configuration accepts the default values for your integration's options.
-`defaults` will be deeply merged with the options provided by the user. Please note that
-this is not runtime safe, it's good practice to check the types of your options inside `setup`.
+- quick snippet
+- alert type note: really read defineOptions docs, super important
+- link to defineOptions
 
-:::caution
-When typing optional properties within your `IntegrationOptions`, make sure to specify `undefined` as a possible value.
+### Using plugins
 
-```ts "undefined"
-interface IntegrationOptions {
-    foo?: string | undefined;
-}
-```
+- how they work
+- corePlugins
+- link to guide to learn how to author them
 
-We recommend that you extend the strictest Astro TSConfig. This will help you create a more stable integration across many platforms and environments.
+### Adding the logic with `setup`
 
-```diff lang="json"
-{
--  "extends": "astro/tsconfigs/strict"
-+  "extends": "astro/tsconfigs/strictest"
-}
-```
-:::
+- arguments passed to setup
+- what to do in setup
+- what to return
diff --git a/docs/src/content/docs/core/define-options.mdx b/docs/src/content/docs/core/define-options.mdx
@@ -5,4 +5,27 @@ description: Allows defining an integration options while keeping the whole thin
 
 Allows defining an integration options while keeping the whole thing type-safe.
 
-WIP
+- why a separate utility (TS madness)
+- explicit generic (extracted)
+- defaults handling (deep-merged)
+- runtime validation + future plans: built-in zod
+- be (type) strict
+
+:::caution
+When typing optional properties within your `IntegrationOptions`, make sure to specify `undefined` as a possible value.
+
+```ts "undefined"
+interface IntegrationOptions {
+    foo?: string | undefined;
+}
+```
+
+We recommend that you extend the strictest Astro TSConfig. This will help you create a more stable integration across many platforms and environments.
+
+```diff lang="json"
+{
+-  "extends": "astro/tsconfigs/strict"
++  "extends": "astro/tsconfigs/strictest"
+}
+```
+:::
diff --git a/docs/src/styles/main.css b/docs/src/styles/main.css
@@ -0,0 +1,41 @@
+/* Dark mode colors. */
+:root {
+	--sl-color-accent-low: #06214e;
+	--sl-color-accent: #005ee1;
+	--sl-color-accent-high: #a9caff;
+	--sl-color-white: #ffffff;
+	--sl-color-gray-1: #ebeef2;
+	--sl-color-gray-2: #bfc2c7;
+	--sl-color-gray-3: #868c95;
+	--sl-color-gray-4: #535961;
+	--sl-color-gray-5: #333941;
+	--sl-color-gray-6: #22272f;
+	--sl-color-black: #16181c;
+    --sl-font: 'Inter var', sans-serif;
+    --sl-font-system-mono: 'JetBrains Mono Variable', monospace;
+}
+/* Light mode colors. */
+:root[data-theme='light'] {
+	--sl-color-accent-low: #c0d8ff;
+	--sl-color-accent: #0060e5;
+	--sl-color-accent-high: #002c72;
+	--sl-color-white: #16181c;
+	--sl-color-gray-1: #22272f;
+	--sl-color-gray-2: #333941;
+	--sl-color-gray-3: #535961;
+	--sl-color-gray-4: #868c95;
+	--sl-color-gray-5: #bfc2c7;
+	--sl-color-gray-6: #ebeef2;
+	--sl-color-gray-7: #f5f6f8;
+	--sl-color-black: #ffffff;
+}
+
+/* jetbrains-mono-latin-wght-normal */
+@font-face {
+  font-family: 'JetBrains Mono Variable';
+  font-style: normal;
+  font-display: swap;
+  font-weight: 100 800;
+  src: url(https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono:vf@latest/latin-wght-normal.woff2) format('woff2-variations');
+  unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0300-0301,U+0303-0304,U+0308-0309,U+0323,U+0329,U+2000-206F,U+2074,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
+}