feat: work on docs

docs/astro.config.ts

@@ -51,7 +51,7 @@ export default defineConfig({
 				},
 			],
 			expressiveCode: {
-				themes: ["one-dark-pro", "starlight-light"]
+				themes: ["one-dark-pro", "starlight-light"],
 			},
 			sidebar: [
 				{
@@ -144,18 +144,14 @@ export default defineConfig({
 					],
 				},
 				{
-					label: `v${version} changelog`,
+					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,

docs/src/components/Disabled.astro

@@ -0,0 +1,5 @@
+<div style="cursor:not-allowed">
+    <div style="opacity: .5;pointer-events:none">
+        <slot />    
+    </div>
+</div>

docs/src/content/docs/core/define-integration.mdx

@@ -2,6 +2,8 @@
 title: defineIntegration
 description: Makes creating integrations easier, and adds a few goodies!
 ---
+import Disabled from "~/components/Disabled.astro"
+import { LinkCard } from '@astrojs/starlight/components';
 
 `defineIntegration` makes creating integrations easier, and adds a few goodies!
 
@@ -17,7 +19,7 @@ type Options = {
     foo?: string | undefined;
 }
 
-export default defineIntegration<{ foo?: string }>({
+export default defineIntegration({
     name: "my-integration",
     options: defineOptions<Options>({ foo: "bar" }),
     plugins: [...corePlugins],
@@ -37,24 +39,116 @@ export default defineIntegration<{ foo?: string }>({
 
 ### Defining an integration
 
-- basic usage
-- never pass generics directly
-- link to guide
+To define an integration, use the `defineIntegration` utility:
+
+```ts title="my-integration/index.ts" "defineIntegration"
+import { defineIntegration } from "astro-integration-kit";
+
+export default defineIntegration({
+    // ...
+    name: "my-integration"
+})
+```
+
+:::caution
+Never pass generics manually to `defineIntegration` or it will break all the
+TypeScript magic of options and plugins.
+:::
+
+<Disabled>
+    <LinkCard
+    title="Authoring an integration (soon)"
+    description="Learn how to write an integration the right way using Astro Integration Kit."
+    href="#"
+    />
+</Disabled>
+
+It accepts a few arguments, whose usage is explained in the sections below.
 
 ### Handling options and defaults
 
-- quick snippet
-- alert type note: really read defineOptions docs, super important
-- link to defineOptions
+`defineIntegration` accepts an `option` argument that you need to use with `defineOptions`.
+
+```ts title="my-integration/index.ts" "defineOptions" ins={3-5,9}
+import { defineIntegration, defineOptions } from "astro-integration-kit";
+
+type Options = {
+    foo?: string | undefined;
+}
+
+export default defineIntegration({
+    // ...
+    options: defineOptions<Options>({ foo: "bar" })
+})
+```
+
+:::note
+Really read the docs about `defineOptions` through the link below, there are limitations and stuff
+you need to know about.
+:::
+
+<LinkCard
+title="Read more about defineOptions"
+description="Allows defining an integration options while keeping the whole thing type-safe."
+href="/core/define-options/"
+/>
 
 ### Using plugins
 
-- how they work
-- corePlugins
-- link to guide to learn how to author them
+Plugins allow us (and you!) to make Astro Integration Kit really powerful. It allows to add arguments
+to built-in hooks in a type-safe way. Get started by using our `corePlugins`:
+
+```ts title="my-integration/index.ts" ins={2,6}
+import { defineIntegration } from "astro-integration-kit";
+import { corePlugins } from "astro-integration-kit/plugins";
+
+export default defineIntegration({
+    // ...
+    plugins: [...corePlugins]
+})
+```
+
+Under the hood, those plugins define using `definePlugin` pass "metadata" as types thanks to generics.
+
+<Disabled>
+    <LinkCard
+    title="Authoring a plugin (soon)"
+    description="Learn how to write an Astro Integration Kit plugin the right way."
+    href="#"
+    />
+</Disabled>
 
 ### Adding the logic with `setup`
 
-- arguments passed to setup
-- what to do in setup
-- what to return
+If you've written an integration before by returning an `AstroIntegration` from a function, that exactly
+the same with `setup`! This is where all the logic lives:
+
+```ts title="my-integration/index.ts" ins={5-7}
+import { defineIntegration } from "astro-integration-kit";
+
+export default defineIntegration({
+    // ...
+    setup() {
+        return {}
+    }
+})
+```
+It accepts an object with data from the integration definition:
+
+```ts title="my-integration/index.ts" "{ options, name }"
+import { defineIntegration } from "astro-integration-kit";
+
+export default defineIntegration({
+    // ...
+    setup({ options, name }) {
+        return {}
+    }
+})
+```
+
+In setup, you'll want to add any logic that is shared between any hook, for example:
+
+- Calling `createResolver`
+- Save the `config` from `astro:config:done` to be used in later hooks
+
+It needs to return Astro hooks. 

docs/src/content/docs/core/define-plugin.mdx

@@ -5,4 +5,11 @@ description: Allows defining a type-safe plugin that can be used in defineIntegr
 
 Allows defining a type-safe plugin that can be used in `defineIntegration`.
 
-WIP
+- Quick snippet
+- Limitations
+    - Overrides
+    - One plugin per hook
+    - Can't be built on other plugins
+- Warning: advanced use-case
+- Integrate with AIK
+- AIK uses this under the hood, have a look at our source for examples

docs/src/content/docs/getting-started/usage.mdx

@@ -2,6 +2,7 @@
 title: Usage
 description: Learn how to use astro-integration-kit in your project.
 ---
+import Disabled from "~/components/Disabled.astro"
 import { LinkCard, Tabs, TabItem } from '@astrojs/starlight/components';
 
 Astro Integration Kit can be used in 2 ways: as **extended hooks** or as **standalone utilities**.
@@ -64,15 +65,13 @@ or one by one as needed.
 
 This allows other developers to easily add their own plugins.
 
-<div style="cursor:not-allowed">
-    <div style="opacity: .5;pointer-events:none">
-        <LinkCard
-        title="Using plugins (soon)"
-        description="Learn how to use plugins to fully take advantage of Astro Integration Kit."
-        href="#"
-        />
-    </div>
-</div>
+<Disabled>
+    <LinkCard
+    title="Using plugins (soon)"
+    description="Learn how to use plugins to fully take advantage of Astro Integration Kit."
+    href="#"
+    />
+</Disabled>
 
 ### Defining an integration
 

docs/src/content/docs/getting-started/why.mdx

@@ -3,19 +3,25 @@ title: Why should you use Astro Integration Kit?
 description: Learn why you should use Astro Integration Kit to build your next Astro Integration.
 ---
 
-Astro Integration Kit is a community-driven effort to improve the power, flexibility, and, most importantly, developer experience of creating Astro Integrations.
+Astro Integration Kit is a **community-driven effort** to improve the power, flexibility, and, most importantly,
+developer experience of creating Astro Integrations.
 
-We are creating the Astro Integration Kit because we want to create a robust, battle-tested suite of tools to make creating Astro integrations easier in the hopes that one day, this will become part of the core Astro framework.
+We are creating the Astro Integration Kit because we want to create a robust, battle-tested suite of tools to make
+creating Astro integrations easier in the hopes that one day, this will become part of the core Astro framework.
 
 We constantly gather feedback from the entire community, from first-time integration builders to the seasoned Astro Core team.
 
-Astro Integration Kit is currently an experimental technology that's still subject to changes as we solidify the APIs. However, it was built from techniques used in production-level integrations across the Astro Ecosystem.
+Astro Integration Kit is currently an **experimental technology** that's still subject to changes as we solidify the APIs.
+However, it was built from techniques used in production-level integrations across the Astro Ecosystem.
 
-Integrations typically require quite a low-level knowledge of Astro and Vite to be made successfully. So, Astro Integration Kit abstracts a lot of low-level implementation into easy-to-use utilities. Things such as Vite Virtual Modules or creating Typescript Declaration files for your users.
+Integrations typically require quite a low-level knowledge of Astro and Vite to be made successfully. So, Astro Integration
+Kit abstracts a lot of low-level implementation into easy-to-use utilities. Things such as Vite Virtual Modules or creating
+Typescript Declaration files for your users.
 
 Small utilities allow you to adhere to best practices with the minimum amount of code.
 
-Once we have a standard way of creating Astro Integrations, we can create content and guides much more easily using well-documented utilities, enabling more people to create more advanced integrations.
+Once we have a standard way of creating Astro Integrations, we can create content and guides much more easily using well-documented
+utilities, enabling more people to create more advanced integrations.
 
 :::note
 We are constantly looking for feedback and contributions from the community. Whether it's contributing code, ideas or suggestions; feel free to create an issue on [our GitHub repository](https://github.com/florian-lefebvre/astro-integration-kit).

docs/src/content/docs/utilities/add-dts.mdx

@@ -7,6 +7,12 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 `addDts` allows you to inject a `.d.ts` file into the user's project. It will
 create a file inside `.astro` and reference it from `src/env.d.ts`. For example:
 
+- quick description
+- quick snippet
+- usage
+- works well with `addVirtualImport`
+- tip: using a template file with placeholders
+
 <Tabs>
     <TabItem label="Extended hooks">
     ```ts title="my-integration/index.ts" "addDts"

docs/tsconfig.json

@@ -1,4 +1,10 @@
 {
   "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
   "exclude": ["dist"]
 }