Integrations

Integrations

Table of Contents

• Giscus comments
• LaTeX equations (KaTeX)
• Google Analytics

Giscus Comments

Giscus enables comments on static sites backed by GitHub Discussions.

Prerequisites

• The repository must be public
• The Giscus GitHub App must be installed on the repository
• GitHub Discussions must be enabled for the repository

Option 1: Simple script tag

1. Go to giscus.app, configure your settings, and copy the generated <script> tag.

2. Open src/layouts/PostLayout.astro and paste the script tag where you want comments to appear (e.g. after the share links):

<Layout {...layoutProps}>
  <main>
    <ShareLinks />

    <script
      src="https://giscus.app/client.js"
      data-repo="your-username/your-repo"
      data-repo-id="YOUR_REPO_ID"
      data-category="YOUR_CATEGORY"
      data-category-id="YOUR_CATEGORY_ID"
      data-mapping="pathname"
      data-strict="0"
      data-reactions-enabled="1"
      data-emit-metadata="0"
      data-input-position="bottom"
      data-theme="preferred_color_scheme"
      data-lang="en"
      crossorigin="anonymous"
      async
    ></script>
  </main>
</Layout>

This approach uses a static theme (preferred_color_scheme), which means Giscus will follow the OS preference but won't sync with AstroPaper's manual theme toggle.

Option 2: React component with theme sync

This approach keeps Giscus in sync with AstroPaper's theme toggle.

1. Install dependencies:

npm i @giscus/react && npx astro add react

2. Create src/components/Comments.tsx:

import Giscus, { type Theme } from "@giscus/react";
import { useEffect, useState } from "react";

interface CommentsProps {
  lightTheme?: Theme;
  darkTheme?: Theme;
}

export default function Comments({
  lightTheme = "light",
  darkTheme = "dark",
}: CommentsProps) {
  const [theme, setTheme] = useState(() => {
    const currentTheme = localStorage.getItem("theme");
    const browserTheme = window.matchMedia("(prefers-color-scheme: dark)")
      .matches
      ? "dark"
      : "light";
    return currentTheme || browserTheme;
  });

  useEffect(() => {
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
    const handleChange = ({ matches }: MediaQueryListEvent) => {
      setTheme(matches ? "dark" : "light");
    };
    mediaQuery.addEventListener("change", handleChange);
    return () => mediaQuery.removeEventListener("change", handleChange);
  }, []);

  useEffect(() => {
    const themeButton = document.querySelector("#theme-btn");
    const handleClick = () => {
      setTheme((prev) => (prev === "dark" ? "light" : "dark"));
    };
    themeButton?.addEventListener("click", handleClick);
    return () => themeButton?.removeEventListener("click", handleClick);
  }, []);

  return (
    <div className="mt-8">
      <Giscus
        repo="your-username/your-repo"
        repoId="YOUR_REPO_ID"
        category="YOUR_CATEGORY"
        categoryId="YOUR_CATEGORY_ID"
        mapping="pathname"
        reactionsEnabled="0"
        emitMetadata="0"
        inputPosition="bottom"
        lang="en"
        loading="lazy"
        theme={theme === "light" ? lightTheme : darkTheme}
      />
    </div>
  );
}

3. Add to src/layouts/PostLayout.astro:

---
import Comments from "@/components/Comments";
---

<ShareLinks />

<Comments client:only="react" />

LaTeX Equations (KaTeX)

AstroPaper supports LaTeX math via KaTeX using remark/rehype plugins.

1. Install the plugins:

pnpm install rehype-katex remark-math katex

2. Update astro.config.ts:

import remarkMath from "remark-math";
import rehypeKatex from "rehype-katex";

export default defineConfig({
  markdown: {
    processor: unified({
      remarkPlugins: [
        remarkMath, // add before remarkToc
        remarkToc,
        [remarkCollapse, { test: "Table of contents" }],
      ],
      rehypePlugins: [
        rehypeCallouts,
        rehypeKatex, // add here
      ],
    }),
    // ...
  },
});

3. Add KaTeX CSS to src/layouts/Layout.astro:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/katex@0.15.2/dist/katex.min.css"
/>

4. Add text color to src/styles/typography.css:

.prose .katex-display {
  @apply text-foreground;
}

Usage in posts:

Inline math (wrapped in $...$):

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Block math (wrapped in $$...$$):

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Google Analytics

AstroPaper does not include Google Analytics by default. The recommended approach is to use Astro's Partytown integration to run analytics in a web worker (avoids blocking the main thread).

1. Install Partytown:

pnpm astro add partytown

2. Add the GA script to src/layouts/Layout.astro:

<!-- Inside <head> -->
<script
  type="text/partytown"
  src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"
></script>
<script type="text/partytown">
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Replace G-XXXXXXXXXX with your Google Analytics Measurement ID.

3. Configure Partytown in astro.config.ts:

import partytown from "@astrojs/partytown";

export default defineConfig({
  integrations: [
    partytown({ config: { forward: ["dataLayer.push"] } }),
    // ...
  ],
});