@stephansama/starlight-giscus 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present, Bugo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# starlight-giscus
+
+This Starlight plugin ties your documentation to GitHub discussions, givin' you a handy way to comment and react.
+
+## Getting Started
+
+Want to get started immediately? Check out the [getting started guide](https://dragomano.github.io/starlight-giscus/getting-started/) or check out the [configuration](https://dragomano.github.io/starlight-giscus/configuration/) to see the available options.
+
+[Starlight Plugins by Example](https://hideoo.dev/notebooks/starlight-plugins-by-example)

package/components/Comments.astro

@@ -0,0 +1,111 @@
+---
+import config from 'virtual:starlight-giscus-config';
+const { entry, lang } = Astro.locals.starlightRoute;
+const {
+    element,
+    repo,
+    repoId,
+    category,
+    categoryId,
+    mapping,
+    reactions,
+    inputPosition,
+    theme,
+    lazy
+} = config;
+const preparedTheme = typeof theme === 'object' ? theme : { auto: theme };
+const giscus = entry.data.giscus ?? true;
+---
+{
+    giscus && (
+        <giscus-comments data-theme={JSON.stringify(preparedTheme)} data-element={element}>
+            <div class="comments">
+                <script is:inline define:vars={{ preparedTheme }}>
+                    (function () {
+                        const palette = localStorage.getItem('starlight-theme') || 'preferred_color_scheme';
+                        const initial = palette === 'dark'
+                            ? (preparedTheme.dark || 'dark')
+                            : (palette === 'light'
+                                ? (preparedTheme.light || 'light')
+                                : (preparedTheme.auto || 'preferred_color_scheme'));
+                        const next = document.currentScript && document.currentScript.nextElementSibling;
+                        if (next) next.setAttribute('data-theme', initial);
+                    })();
+                </script>
+                <script
+                    is:inline
+                    src="https://giscus.app/client.js"
+                    data-repo={repo}
+                    data-repo-id={repoId}
+                    data-category={category}
+                    data-category-id={categoryId}
+                    data-mapping={mapping}
+                    data-strict="1"
+                    data-reactions-enabled={+reactions}
+                    data-emit-metadata="0"
+                    data-input-position={inputPosition}
+                    data-theme={preparedTheme.auto}
+                    data-lang={lang}
+                    data-loading={lazy ? 'lazy' : null}
+                    crossorigin="anonymous"
+                    async
+                >
+                </script>
+            </div>
+        </giscus-comments>
+
+        <script>
+            class GiscusComments extends HTMLElement {
+                constructor() {
+                    super();
+
+                    const theme = JSON.parse(this.dataset.theme!)
+                    const element = this.dataset.element || 'starlight-theme-select'
+                    const darkTheme = theme.dark || 'dark';
+                    const lightTheme = theme.light || 'light';
+                    const preferredTheme = theme.auto || 'preferred_color_scheme';
+
+                    const getThemeValue = (fallback = 'preferred_color_scheme') => {
+                        const palette = localStorage.getItem('starlight-theme') || fallback
+
+                        return palette === 'dark'
+                            ? darkTheme
+                            : (palette === 'light' ? lightTheme : preferredTheme)
+                    }
+
+                    function setGiscusTheme() {
+                        const frame: HTMLIFrameElement = document.querySelector('iframe.giscus-frame')!
+                        const theme = getThemeValue();
+
+                        frame.contentWindow?.postMessage(
+                            {
+                                giscus: {
+                                    setConfig: {
+                                        theme: theme
+                                    }
+                                }
+                            },
+                            '*'
+                        )
+                    }
+
+                    function handleGiscusMessage(event: MessageEvent) {
+                        if (event.origin !== 'https://giscus.app') return;
+                        if (!(typeof event.data === 'object' && event.data.giscus)) return;
+                        setGiscusTheme();
+                    }
+
+                    window.addEventListener('message', handleGiscusMessage);
+
+                    document.addEventListener('DOMContentLoaded', function() {
+                        const ref: Element = document.querySelector(element)!
+
+                        ref.addEventListener('change', setGiscusTheme)
+                    })
+                }
+            }
+
+            customElements.define('giscus-comments', GiscusComments);
+        </script>
+    )
+}

package/index.ts

@@ -0,0 +1,124 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { AstroError } from 'astro/errors';
+import { vitePluginStarlightGiscusConfig } from './libs/vite';
+import { overrideStarlightComponent } from './libs/starlight';
+
+export interface StarlightGiscusThemeObject {
+  light?: string;
+  dark?: string;
+  auto?: string;
+}
+
+export type StarlightGiscusTheme = string | StarlightGiscusThemeObject;
+
+export interface StarlightGiscusUserConfig {
+  element?: string;
+  repo: string;
+  repoId: string;
+  category: string;
+  categoryId: string;
+  mapping?: string;
+  reactions?: boolean;
+  inputPosition?: string;
+  theme?: StarlightGiscusTheme;
+  lazy?: boolean;
+}
+
+export interface StarlightGiscusConfig {
+  element: string;
+  repo: string;
+  repoId: string;
+  category: string;
+  categoryId: string;
+  mapping: string;
+  reactions: boolean;
+  inputPosition: string;
+  theme: string | StarlightGiscusThemeObject;
+  lazy: boolean;
+}
+
+function validateAndNormalizeConfig(
+  options: StarlightGiscusUserConfig
+): StarlightGiscusConfig {
+  // Validate required fields
+  const requiredFields: (keyof StarlightGiscusUserConfig)[] = [
+    'repo',
+    'repoId',
+    'category',
+    'categoryId',
+  ];
+
+  for (const field of requiredFields) {
+    if (!options[field]) {
+      throw new AstroError(
+        `The provided plugin configuration is invalid. Missing required field: ${field}`
+      );
+    }
+  }
+
+  // Normalize theme
+  let normalizedTheme: StarlightGiscusConfig['theme'];
+  if (typeof options.theme === 'object' && options.theme !== null) {
+    normalizedTheme = {
+      light: options.theme.light ?? 'light',
+      dark: options.theme.dark ?? 'dark',
+      auto: options.theme.auto ?? 'preferred_color_scheme',
+    };
+  } else {
+    normalizedTheme = options.theme ?? 'preferred_color_scheme';
+  }
+
+  // Return config with defaults
+  return {
+    element: options.element ?? 'starlight-theme-select',
+    repo: options.repo,
+    repoId: options.repoId,
+    category: options.category,
+    categoryId: options.categoryId,
+    mapping: options.mapping ?? 'pathname',
+    reactions: options.reactions ?? true,
+    inputPosition: options.inputPosition ?? 'bottom',
+    theme: normalizedTheme,
+    lazy: options.lazy ?? false,
+  };
+}
+
+export { validateAndNormalizeConfig };
+
+export default function starlightGiscus(
+  options: StarlightGiscusUserConfig
+): StarlightPlugin {
+  const config = validateAndNormalizeConfig(options);
+
+  return {
+    name: 'starlight-giscus',
+    hooks: {
+      'config:setup'({ logger, config: starlightConfig, updateConfig, addIntegration }) {
+        updateConfig({
+          components: {
+            ...starlightConfig.components,
+            ...overrideStarlightComponent(
+              starlightConfig.components,
+              logger,
+              'Pagination',
+              'Pagination'
+            ),
+          },
+        });
+
+        addIntegration({
+          name: 'starlight-giscus-integration',
+          hooks: {
+            'astro:config:setup': ({ updateConfig }) => {
+              updateConfig({
+                vite: {
+                  plugins: [vitePluginStarlightGiscusConfig(config)],
+                },
+              });
+            },
+          },
+        });
+      },
+    },
+  };
+}

package/libs/starlight.ts

@@ -0,0 +1,24 @@
+import type { StarlightUserConfig } from '@astrojs/starlight/types';
+import type { AstroIntegrationLogger } from 'astro';
+
+export function overrideStarlightComponent(
+  components: StarlightUserConfig['components'],
+  logger: AstroIntegrationLogger,
+  override: keyof NonNullable<StarlightUserConfig['components']>,
+  component: string
+) {
+  if (components?.[override]) {
+    logger.warn(
+      `It looks like you already have a \`${String(override)}\` component override in your Starlight configuration.`
+    );
+    logger.warn(
+      `To use \`starlight-giscus\`, either remove your override or update it to render the content from \`starlight-giscus/components/${component}.astro\`.`
+    );
+
+    return {};
+  }
+
+  return {
+    [override]: `starlight-giscus/overrides/${String(override)}.astro`,
+  };
+}

package/libs/vite.ts

@@ -0,0 +1,38 @@
+import type { ViteUserConfig } from 'astro';
+import type { StarlightGiscusConfig } from '..';
+
+export function vitePluginStarlightGiscusConfig(
+  starlightGiscusConfig: StarlightGiscusConfig
+): VitePlugin {
+  const modules = {
+    'virtual:starlight-giscus-config': `export default ${JSON.stringify(
+      starlightGiscusConfig
+    )}`,
+  };
+
+  const moduleResolutionMap = Object.fromEntries(
+    (Object.keys(modules) as (keyof typeof modules)[]).map((key) => [
+      resolveVirtualModuleId(key),
+      key,
+    ])
+  );
+
+  return {
+    name: 'vite-plugin-starlight-giscus',
+    load(id) {
+      const moduleId = moduleResolutionMap[id];
+      return moduleId ? modules[moduleId] : undefined;
+    },
+    resolveId(id) {
+      return id in modules ? resolveVirtualModuleId(id) : undefined;
+    },
+  };
+}
+
+function resolveVirtualModuleId<TModuleId extends string>(
+  id: TModuleId
+): `\0${TModuleId}` {
+  return `\0${id}`;
+}
+
+type VitePlugin = NonNullable<ViteUserConfig['plugins']>[number];

package/overrides/Pagination.astro

@@ -0,0 +1,7 @@
+---
+import Default from '@astrojs/starlight/components/Pagination.astro';
+import Comments from '../components/Comments.astro';
+---
+
+<Comments />
+<Default />

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@stephansama/starlight-giscus",
+  "version": "0.9.1",
+  "license": "MIT",
+  "description": "A Starlight plugin for adding Giscus comments to your documentation.",
+  "keywords": [
+    "starlight",
+    "starlight-plugin",
+    "giscus",
+    "discussions",
+    "github-discussions",
+    "reactions",
+    "comments"
+  ],
+  "author": "Bugo",
+  "type": "module",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./components/Comments.astro": "./components/Comments.astro",
+    "./overrides/Pagination.astro": "./overrides/Pagination.astro",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "tsc-files": "^1.1.4",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.37.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "homepage": "https://github.com/dragomano/starlight-giscus",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dragomano/starlight-giscus.git",
+    "directory": "packages/starlight-giscus"
+  },
+  "bugs": "https://github.com/dragomano/starlight-giscus/issues",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc-files --noEmit index.ts libs/starlight.ts libs/vite.ts tests/*.test.ts"
+  }
+}

package/virtual.d.ts

@@ -0,0 +1,4 @@
+declare module "virtual:starlight-giscus-config" {
+  const StarlightGiscusConfig: import("./index").StarlightGiscusConfig;
+  export default StarlightGiscusConfig;
+}