Spec-Driven Development: A Practical Guide with SpecKit#

1
# Feature Specification: Giscus Comments Integration
2

3
## Feature Overview
4

5
Enable blog post comments using **Giscus** - a comments system
6
powered by GitHub Discussions. Readers can discuss posts using
7
their GitHub accounts without leaving the blog.
8

9
## User Stories
10

11
### US1: Display Giscus Comments Widget (P1)
12

13
**As a** blog reader
14
**I want to** see a comments section under blog posts
15
**So that** I can read and participate in discussions
16

17
**Acceptance Criteria**:
18
- Giscus widget loads on posts where commentsEnabled: true
19
- Widget displays existing discussion comments from GitHub
20
- Widget matches blog's light/dark theme automatically
21
- Loading state shows graceful placeholder
22
- Widget is responsive on all screen sizes

1
## Non-Goals
2

3
- Custom comment UI (use Giscus default)
4
- Email notifications (handled by GitHub)
5
- Comment editing within blog (use GitHub Discussions)
6
- Anonymous comments (GitHub authentication required)

1
# Implementation Plan: Giscus Comments Integration
2

3
## Constitution Compliance Check
4

5
✅ Preservation-First: Fuwari template structure untouched
6
✅ Minimal Change: Single new component
7
✅ Component Isolation: Zero dependencies on existing components
8
✅ Configuration Over Code: All settings in src/config.ts
9
✅ Development Validation: TypeScript strict mode enabled
10

11
## Tech Stack Analysis
12

13
**Existing Stack**:
14
- Framework: Astro 5.x (SSG)
15
- UI: Svelte 5
16
- Styling: Tailwind CSS 3.x
17
- Package Manager: pnpm
18

19
**New Dependencies**:
20
- Giscus: CDN-hosted script (no npm dependencies needed)
21

22
## Implementation Strategy
23

24
### Phase 1: Setup & Configuration
25
- Create src/types/giscus.ts
26
- Add giscusConfig to src/config.ts
27
- Extend content schema
28

29
### Phase 2: Component Implementation
30
- Create GiscusComments.svelte
31
- Dynamic script injection via onMount
32
- Handle theme synchronization

1
src/
2
├── components/
3
│   └── GiscusComments.svelte          (NEW - 50 lines)
4
├── types/
5
│   └── giscus.ts                       (NEW - 20 lines)
6
├── config.ts                           (MODIFY - add 15 lines)

1
## Phase 1: Setup & Type Definitions
2

3
- [ ] T001 Create specs/002-giscus-comments/ directory structure
4
- [ ] T002 Create src/types/giscus.ts with interfaces
5
- [ ] T003 Verify existing dependencies
6

7
## Phase 2: Configuration & Schema
8

9
- [ ] T004 Add giscusConfig export to src/config.ts
10
- [ ] T005 Extend postsCollection schema with commentsEnabled field
11
- [ ] T006 Update .gitignore if needed
12

13
## Phase 3: Component Implementation
14

15
- [ ] T007 [US1] Create GiscusComments.svelte skeleton
16
- [ ] T008 [US1] Implement onMount hook for script injection
17
- [ ] T009 [US1] Set all data-* attributes from config

1
<script lang="ts">
2
  import { onMount } from "svelte";
3
  import { giscusConfig } from "@/config";
4

5
  interface Props {
6
    discussionNumber?: number;
7
    class?: string;
8
  }
9

10
  let { discussionNumber, class: className = "" }: Props = $props();
11
  let container: HTMLDivElement;
12

13
  onMount(() => {
14
    const script = document.createElement("script");
15
    script.src = "https://giscus.app/client.js";
16
    script.setAttribute("data-repo", giscusConfig.repo);
17
    script.setAttribute("data-repo-id", giscusConfig.repoId);
18
    script.setAttribute("data-category", giscusConfig.category);
19
    script.setAttribute("data-category-id", giscusConfig.categoryId);
20

21
    if (discussionNumber) {
22
      script.setAttribute("data-mapping", "number");
23
      script.setAttribute("data-discussion-number", discussionNumber.toString());
24
    } else {
25
      script.setAttribute("data-mapping", giscusConfig.mapping);
26
    }
27

28
    script.setAttribute("data-strict", "0");
29
    script.setAttribute("data-reactions-enabled",
30
      giscusConfig.reactionsEnabled ? "1" : "0");
31
    script.setAttribute("data-theme", giscusConfig.theme);
32
    script.setAttribute("data-lang", giscusConfig.lang);
33
    script.crossOrigin = "anonymous";
34
    script.async = true;
35

36
    container.appendChild(script);
37
  });
38
</script>
39

40
<div bind:this={container} class="giscus-container w-full {className}"></div>