CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a VitePress-based documentation site for Answer IO's user manual, hosted at docs.answer-io.jp. Answer IO is a platform for tracking brand visibility across AI search engines.

Development Commands

# Start development server (hot reload enabled)
npm run dev

# Build for production
npm run build
# or
npm run docs:build

# Preview production build
npm run preview
# or
npm run docs:preview

Development server runs at http://localhost:5173

Tech Stack

• Framework: VitePress v1.3.4
• Language: TypeScript
• UI Framework: Vue 3
• Deployment: GitHub Pages via GitHub Actions
• Domain: docs.answer-io.jp

Project Structure

├── .vitepress/
│   ├── config.ts              # VitePress configuration
│   ├── theme/
│   │   ├── index.ts           # Custom theme entry point
│   │   ├── style.css          # Custom styles
│   │   └── components/
│   │       ├── PasswordProtection.vue  # Password overlay component
│   │       └── YouTubeEmbed.vue        # YouTube video embed component
│   └── dist/                  # Build output (generated)
├── index.md                   # Root homepage (http://localhost:5173/)
├── ja/                        # Japanese content
│   ├── index.md               # Japanese homepage (http://localhost:5173/ja/)
│   ├── getting-started/       # Getting started guides
│   └── glossary.md            # Glossary
├── public/                    # Static assets (logo, images, etc.)
├── .github/workflows/
│   └── deploy.yml             # GitHub Actions deployment workflow
└── package.json

Key Features

Password Protection

The site includes an optional password protection overlay:

• Controlled via environment variables in .vitepress/config.ts
• VITE_ENABLE_PASSWORD_PROTECTION: Enable/disable password protection (values: 'true', 'TRUE', 'false')
• VITE_SITE_PASSWORD: The password required to access the site
• Password state is stored in sessionStorage
• Overlay component: .vitepress/theme/components/PasswordProtection.vue
• The overlay is only shown after mounting (SSR-safe implementation)

Custom Theme

The site extends VitePress's default theme:

• Theme entry: .vitepress/theme/index.ts
• Custom Layout wraps the default theme with PasswordProtection component
• Custom styles in .vitepress/theme/style.css

VitePress Configuration

Key configuration points in .vitepress/config.ts:

• Base path: Set to / for custom domain (docs.answer-io.jp)
• srcExclude: Excludes answer-io-standalone/ submodule (not compatible with VitePress markdown)
• Environment injection: Uses vite.define to inject password protection settings
• Localization: Japanese locale with search translations
• SEO: Comprehensive meta tags, OGP, and Twitter Card support
• Navigation: Configured via themeConfig.nav and themeConfig.sidebar

Content Management

Adding New Pages

1. Create new .md file in appropriate directory (e.g., ja/guide/new-page.md)
2. Add to sidebar configuration in .vitepress/config.ts:

sidebar: {
  '/ja/': [
    {
      text: 'Section Name',
      items: [
        { text: 'Page Title', link: '/ja/guide/new-page' }
      ]
    }
  ]
}

Markdown Features

VitePress supports:

• Frontmatter for page metadata
• Custom containers: ::: tip, ::: warning, ::: danger
• Code blocks with syntax highlighting
• Internal links using relative paths
• Vue components in markdown

Embedding YouTube Videos

The site includes a custom YouTubeEmbed component for embedding YouTube videos:

Component location: .vitepress/theme/components/YouTubeEmbed.vue

Usage in markdown:

<YouTubeEmbed videoId="VIDEO_ID" title="Video Title" />

Features:

• Responsive 16:9 aspect ratio
• Styled with rounded corners
• Supports all standard YouTube iframe features
• Registered globally in .vitepress/theme/index.ts

Example:

<YouTubeEmbed videoId="5bTjEct_iDY" title="Answer IOの使い方 - 7分でわかる基本操作" />

Current implementations:

• /index.md - Root homepage quick start section
• /ja/index.md - Japanese homepage quick start section
• /ja/getting-started/index.md - Getting started guide

Deployment

GitHub Actions Workflow

Automatic deployment on push to main branch:

• Workflow file: .github/workflows/deploy.yml
• Builds VitePress site
• Copies CNAME file to dist directory
• Deploys to GitHub Pages
• Environment variables injected via GitHub Secrets:
  • VITE_ENABLE_PASSWORD_PROTECTION
  • VITE_SITE_PASSWORD

DNS Configuration

Custom domain setup:

• CNAME record pointing docs to GitHub Pages
• CNAME file in root directory contains docs.answer-io.jp
• HTTPS enforced via GitHub Pages settings

Development Notes

1. Submodule Exclusion: The answer-io-standalone/ directory is a Git submodule that contains the main application codebase. It is explicitly excluded from VitePress processing via srcExclude to avoid markdown parsing conflicts.

2. Password Protection Implementation:

   • Uses Vue 3 composition API with ref and computed
   • SSR-safe: Only shows overlay after client-side mounting (onMounted)
   • Environment variables injected at build time via Vite's define option
   • sessionStorage used for authentication state (requires client-side JavaScript)

3. Build Output: Generated files go to .vitepress/dist/. The CNAME file is copied there during GitHub Actions deployment.

4. Theme Customization: To modify the theme, edit files in .vitepress/theme/. The custom theme extends VitePress's DefaultTheme while adding the password protection layer.

5. Content Language: All user-facing content is in Japanese. Navigation, search, and UI elements use Japanese translations.

6. File Structure for Homepage:

   • /index.md corresponds to http://localhost:5173/ (root homepage)
   • /ja/index.md corresponds to http://localhost:5173/ja/ (Japanese homepage)
   • Both files use layout: home and contain similar content structure
   • When adding content to the homepage, update both files to maintain consistency

7. YouTube Video Embeds:

   • Uses custom YouTubeEmbed Vue component (.vitepress/theme/components/YouTubeEmbed.vue)
   • Component is globally registered in .vitepress/theme/index.ts
   • Works in both layout: home and layout: doc pages
   • Provides consistent styling and responsive behavior across all video embeds