Merge pull request #23 from HiDeoo/hd-plugin

.github/workflows/integration.yml

@@ -46,7 +46,7 @@ jobs:
 
       - name: Generates TypeScript types
         run: pnpm astro sync
-        working-directory: example
+        working-directory: docs
 
       - name: Lint
         run: pnpm lint

.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "eslint.experimental.useFlatConfig": true,
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact",
+    "html",
+    "vue",
+    "markdown",
+    "astro"
+  ]
+}

example/README.md → docs/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <h1>starlight-blog 📰</h1>
-  <p>Astro integration for Starlight to add a blog to your documentation.</p>
+  <p>Starlight plugin to add a blog to your documentation.</p>
 </div>
 
 <div align="center">
@@ -13,9 +13,9 @@
   <br />
 </div>
 
-## Example
+## Documentation
 
-Run the example locally using your favorite package manager, e.g. with [pnpm](https://pnpm.io):
+Run the documentation locally using your favorite package manager, e.g. with [pnpm](https://pnpm.io):
 
 ```shell
 pnpm run dev

docs/astro.config.mjs

@@ -0,0 +1,47 @@
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import starlightBlog from 'starlight-blog'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      customCss: ['./src/styles/custom.css'],
+      editLink: {
+        baseUrl: 'https://github.com/HiDeoo/starlight-blog/edit/main/docs/',
+      },
+      plugins: [
+        starlightBlog({
+          title: 'Demo Blog',
+          authors: {
+            hideoo: {
+              name: 'HiDeoo',
+              title: 'Starlight Aficionado',
+              picture: '/hideoo.png',
+              url: 'https://hideoo.dev',
+            },
+          },
+        }),
+      ],
+      sidebar: [
+        {
+          label: 'Start Here',
+          items: [
+            { label: 'Getting Started', link: '/getting-started/' },
+            { label: 'Configuration', link: '/configuration/' },
+          ],
+        },
+        {
+          label: 'Guides',
+          items: [
+            { label: 'Frontmatter', link: '/guides/frontmatter/' },
+            { label: 'Authors', link: '/guides/authors/' },
+          ],
+        },
+      ],
+      social: {
+        github: 'https://github.com/HiDeoo/starlight-blog',
+      },
+      title: 'Starlight Blog',
+    }),
+  ],
+})

example/package.json → docs/package.json

@@ -1,8 +1,8 @@
 {
-  "name": "starlight-blog-example",
+  "name": "starlight-blog-docs",
   "version": "0.4.0",
   "license": "MIT",
-  "description": "Astro integration for Starlight to add a blog to your documentation.",
+  "description": "Starlight plugin to add a blog to your documentation.",
   "author": "HiDeoo <[email protected]> (https://hideoo.dev)",
   "type": "module",
   "scripts": {
@@ -14,8 +14,8 @@
     "lint": "prettier -c --cache . && eslint . --cache --max-warnings=0"
   },
   "dependencies": {
-    "@astrojs/starlight": "0.11.0",
-    "astro": "3.2.3",
+    "@astrojs/starlight": "0.19.0",
+    "astro": "4.2.7",
     "sharp": "0.32.5",
     "starlight-blog": "workspace:*"
   },
@@ -27,10 +27,10 @@
   "sideEffects": false,
   "keywords": [
     "starlight",
+    "plugin",
     "blog",
     "documentation",
-    "astro",
-    "astro-integration"
+    "astro"
   ],
   "homepage": "https://github.com/HiDeoo/starlight-blog",
   "repository": {

docs/src/content/config.ts

@@ -0,0 +1,8 @@
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
+import { defineCollection } from 'astro:content'
+import { blogSchema } from 'starlight-blog/schema'
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema({ extend: blogSchema() }) }),
+  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+}

docs/src/content/docs/configuration.md

@@ -0,0 +1,104 @@
+---
+title: Configuration
+description: An overview of all the configuration options supported by the Starlight Blog plugin.
+---
+
+The Starlight Blog plugin can be configured inside the `astro.config.mjs` configuration file of your project:
+
+```js {11}
+// astro.config.mjs
+import starlight from '@astrojs/starlight'
+import { defineConfig } from 'astro/config'
+import starlightBlog from 'starlight-blog'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      plugins: [
+        starlightBlog({
+          // Configuration options go here.
+        }),
+      ],
+      title: 'My Docs',
+    }),
+  ],
+})
+```
+
+## Plugin configuration
+
+The Starlight Blog plugin accepts the following configuration options:
+
+### `title`
+
+**Type:** `string`  
+**Default:** `'Blog'`
+
+The title of the blog.
+
+### `postCount`
+
+**Type:** `number`  
+**Default:** `5`
+
+The number of blog posts to display per page in the blog post list.
+
+### `recentPostCount`
+
+**Type:** `number`  
+**Default:** `10`
+
+The number of recent blog posts to display in the blog sidebar.
+
+### `authors`
+
+**Type:** [`StarlightBlogAuthorsConfig`](#author-configuration)
+
+A list of global authors for all blog posts or regular authors that can be referenced in individual blog posts.
+Check the ["Authors" guide](/guides/authors) section for more informations.
+
+## Author configuration
+
+Global authors for all blog posts or regular authors that can be referenced in individual blog posts can be defined using the [`authors`](#authors) configuration option.
+When a blog post frontmatter does not define an author, the global authors from the configuration will be used instead.
+Check the ["Authors" guide](/guides/authors) for more informations.
+
+```js {4-9}
+// astro.config.mjs
+starlightBlog({
+  authors: {
+    alice: {
+      // Author configuration for the `alice` author goes here.
+    },
+    bob: {
+      // Author configuration for the `bob` author goes here.
+    },
+  },
+})
+```
+
+An author can be configured using the following options:
+
+### `name` (required)
+
+**Type:** `string`
+
+The name of the author.
+
+### `title`
+
+**Type:** `string`
+
+A title to display below the author's name.
+
+### `url`
+
+**Type:** `string`
+
+A URL to link the author's name to.
+
+### `picture`
+
+**Type:** `string`
+
+A URL or path to an image in the `public/` directory to display as the author's picture.

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

@@ -0,0 +1,118 @@
+---
+title: Getting Started
+description: Learn how to add a blog to your documentation site using the Starlight Blog plugin.
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components'
+
+A [Starlight](https://starlight.astro.build) plugin to add a blog to your documentation site.
+
+- Link to the blog in the header
+- Post list with pagination
+- Global and per-post authors
+- Tags
+- Custom sidebar with recent posts and tags
+
+Check out the [demo](/blog/) for a preview of the blog.
+
+## Prerequisites
+
+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 Blog is a Starlight [plugin](https://starlight.astro.build/reference/plugins/).
+Install it using your favorite package manager:
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+npm install starlight-blog
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+pnpm add starlight-blog
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+yarn add starlight-blog
+```
+
+</TabItem>
+<TabItem label="Bun">
+
+```sh
+bun add starlight-blog
+```
+
+</TabItem>
+<TabItem label="ni">
+
+```sh
+ni starlight-blog
+```
+
+</TabItem>
+</Tabs>
+
+## Configure the plugin
+
+The Starlight Blog 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 starlightBlog from 'starlight-blog'
+
+export default defineConfig({
+  integrations: [
+    starlight({
++      plugins: [starlightBlog()],
+      title: 'My Docs',
+    }),
+  ],
+})
+```
+
+The Starlight Blog plugin behavior can be tweaked using various [configuration options](/configuration).
+
+## Extend frontmatter schema
+
+Extend Starlight's frontmatter default schema to add support for customizing individual blog posts using their frontmatter in the `src/content/config.ts` file:
+
+```diff lang="ts" ins="{ extend: blogSchema() }"
+// src/content/config.ts
+import { defineCollection } from 'astro:content';
+import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
++import { blogSchema } from 'starlight-blog/schema'
+
+export const collections = {
+	docs: defineCollection({ schema: docsSchema({ extend: blogSchema() }) }),
+	i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
+};
+```
+
+## Create your first blog post
+
+Create your first blog post by creating a `.md` or `.mdx` file in the `src/content/docs/blog/` directory:
+
+```md
+---
+// src/content/docs/blog/my-first-blog-post.md
+title: My first blog post
+date: 2023-07-24
+---
+
+## Hello
+
+Hello world!
+```