docs: add Astro Starlight documentation site

docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/astro.config.mjs

@@ -0,0 +1,55 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  site: 'https://react-shiki.vercel.app',
+  integrations: [
+    starlight({
+      title: 'react-shiki',
+      description: 'A performant client-side syntax highlighting component and hook for React, built with Shiki.',
+      social: {
+        github: 'https://github.com/AVGVSTVS96/react-shiki',
+      },
+      logo: {
+        src: './src/assets/shiki-logo.svg',
+        replacesTitle: false,
+      },
+      editLink: {
+        baseUrl: 'https://github.com/AVGVSTVS96/react-shiki/edit/main/docs/',
+      },
+      customCss: [
+        './src/styles/custom.css',
+      ],
+      sidebar: [
+        {
+          label: 'Getting Started',
+          items: [
+            { label: 'Introduction', slug: 'getting-started/introduction' },
+            { label: 'Installation', slug: 'getting-started/installation' },
+            { label: 'Quick Start', slug: 'getting-started/quick-start' },
+          ],
+        },
+        {
+          label: 'Guides',
+          items: [
+            { label: 'Bundle Options', slug: 'guides/bundle-options' },
+            { label: 'Themes', slug: 'guides/themes' },
+            { label: 'Languages', slug: 'guides/languages' },
+            { label: 'Line Numbers', slug: 'guides/line-numbers' },
+            { label: 'Transformers', slug: 'guides/transformers' },
+            { label: 'react-markdown Integration', slug: 'guides/react-markdown' },
+            { label: 'Performance', slug: 'guides/performance' },
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'Component Props', slug: 'reference/component-props' },
+            { label: 'Hook Options', slug: 'reference/hook-options' },
+            { label: 'RegExp Engines', slug: 'reference/regexp-engines' },
+          ],
+        },
+      ],
+    }),
+  ],
+});

docs/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.32.0",
+    "astro": "^5.7.0",
+    "sharp": "^0.33.5"
+  }
+}

docs/src/content.config.ts

@@ -0,0 +1,6 @@
+import { docsSchema } from '@astrojs/starlight/schema';
+import { defineCollection } from 'astro:content';
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+};

docs/src/content/docs/getting-started/installation.md

@@ -0,0 +1,46 @@
+---
+title: Installation
+description: Install react-shiki in your React project.
+---
+
+## Prerequisites
+
+react-shiki requires React 17 or later.
+
+## Install via npm
+
+```bash
+npm install react-shiki
+```
+
+## Install via pnpm
+
+```bash
+pnpm add react-shiki
+```
+
+## Install via yarn
+
+```bash
+yarn add react-shiki
+```
+
+## Bundle Options
+
+react-shiki offers three different entry points to balance convenience and bundle size:
+
+| Entry Point | Size (gzipped) | Description |
+|-------------|----------------|-------------|
+| `react-shiki` | ~1.2MB | Full bundle with all languages and themes |
+| `react-shiki/web` | ~695KB | Web-focused languages only |
+| `react-shiki/core` | ~12KB | Minimal core, BYO themes and languages |
+
+See the [Bundle Options](/guides/bundle-options/) guide for detailed information on choosing the right bundle for your project.
+
+## TypeScript Support
+
+react-shiki includes TypeScript definitions out of the box. No additional `@types` packages are required.
+
+## Next Steps
+
+Continue to the [Quick Start](/getting-started/quick-start/) guide to start highlighting code!

docs/src/content/docs/getting-started/introduction.md

@@ -0,0 +1,29 @@
+---
+title: Introduction
+description: Learn about react-shiki and its capabilities for syntax highlighting in React applications.
+---
+
+**react-shiki** is a performant client-side syntax highlighting library for React applications, built on top of [Shiki](https://shiki.matsu.io/).
+
+## What is react-shiki?
+
+react-shiki provides both a component and a hook for syntax highlighting in React applications. It leverages Shiki's powerful TextMate grammar-based highlighting engine to produce accurate, beautiful syntax highlighting.
+
+## Key Features
+
+- **Component & Hook API** — Use the `ShikiHighlighter` component for quick setup or the `useShikiHighlighter` hook for more flexibility
+- **Flexible Output** — Choose between React elements (safer, no `dangerouslySetInnerHTML`) or HTML strings for better performance
+- **Multiple Bundle Options** — Full bundle with all languages, web-focused bundle, or minimal core for maximum control
+- **Custom Themes & Languages** — Full support for custom TextMate themes and language grammars
+- **Streaming Support** — Performant highlighting of streamed code with optional throttling
+- **Line Numbers** — CSS-based line numbers with customizable styling
+- **Transformers** — Support for Shiki transformers to modify highlighting output
+- **Minimal Default Styles** — Includes sensible defaults that can be easily customized
+
+## Demo
+
+Check out the [live demo](https://react-shiki.vercel.app/) to see react-shiki in action with various themes and languages!
+
+## Next Steps
+
+Ready to get started? Head to the [Installation](/getting-started/installation/) guide to add react-shiki to your project.

docs/src/content/docs/getting-started/quick-start.md

@@ -0,0 +1,108 @@
+---
+title: Quick Start
+description: Get up and running with react-shiki in minutes.
+---
+
+This guide will get you highlighting code in just a few minutes.
+
+## Using the Component
+
+The simplest way to use react-shiki is with the `ShikiHighlighter` component:
+
+```tsx
+import ShikiHighlighter from "react-shiki";
+
+function CodeBlock() {
+  const code = `function greet(name: string) {
+  return \`Hello, \${name}!\`;
+}`;
+
+  return (
+    <ShikiHighlighter language="typescript" theme="github-dark">
+      {code}
+    </ShikiHighlighter>
+  );
+}
+```
+
+The component automatically:
+- Displays a language label in the top-right corner
+- Applies minimal default styling
+- Handles loading states gracefully
+
+## Using the Hook
+
+For more control over rendering, use the `useShikiHighlighter` hook:
+
+```tsx
+import { useShikiHighlighter } from "react-shiki";
+
+function CodeBlock({ code, language }) {
+  const highlightedCode = useShikiHighlighter(code, language, "github-dark");
+
+  return <div className="code-block">{highlightedCode}</div>;
+}
+```
+
+The hook returns `null` while loading and the highlighted React elements when ready.
+
+## Common Props and Options
+
+Both the component and hook accept similar configuration options:
+
+```tsx
+// Component with options
+<ShikiHighlighter
+  language="typescript"
+  theme="github-dark"
+  showLanguage={true}      // Show language label (component only)
+  showLineNumbers={true}   // Display line numbers
+  delay={150}              // Throttle updates (ms)
+>
+  {code}
+</ShikiHighlighter>
+
+// Hook with options
+const highlighted = useShikiHighlighter(code, "typescript", "github-dark", {
+  showLineNumbers: true,
+  delay: 150,
+});
+```
+
+## Multi-Theme Support
+
+Use different themes for light and dark modes:
+
+```tsx
+<ShikiHighlighter
+  language="typescript"
+  theme={{
+    light: "github-light",
+    dark: "github-dark",
+  }}
+  defaultColor="light-dark()"
+>
+  {code}
+</ShikiHighlighter>
+```
+
+With `defaultColor="light-dark()"`, the theme automatically switches based on the user's color scheme preference.
+
+## Web Bundle for Smaller Size
+
+If you only need web-focused languages, use the web bundle:
+
+```tsx
+import ShikiHighlighter from "react-shiki/web";
+
+// Same API, smaller bundle (~695KB vs ~1.2MB gzipped)
+<ShikiHighlighter language="javascript" theme="vitesse-dark">
+  {code}
+</ShikiHighlighter>
+```
+
+## Next Steps
+
+- Learn about [Bundle Options](/guides/bundle-options/) to optimize your bundle size
+- Explore [Themes](/guides/themes/) for multi-theme and custom theme support
+- See [react-markdown Integration](/guides/react-markdown/) for markdown rendering