Customization Guide

This guide helps you customize your Astro theme. It’s divided into two parts: content editing for non-developers, and technical setup for developers.

日本語版ドキュメント

Requirements

Node.js 22.12.0+
npm 9.0.0+
Astro (check package.json for version)

Theme Structure

/
├── src/
│   ├── config/         # JSON configs (site, menu, FAQ, team, etc.)
│   ├── data/           # Markdown content
│   ├── assets/         # Images, icons, and media files (Astro v6 themes include fonts/ here)
│   ├── components/
│   │   ├── layout/     # Header, Footer, etc.
│   │   ├── sections/   # pre-built sections
│   │   ├── ui/         # Reusable UI components
│   │   └── util/       # Utility components
│   ├── layouts/        # Page layouts
│   ├── pages/          # Route pages
│   ├── styles/         # Design tokens, global styles
│   └── types/
│       └── index.d.ts  # TypeScript type definitions
├── public/
│   ├── fonts/          # Web fonts (Astro v6 themes move this to src/assets/fonts/)
│   ├── images/         # Static images
│   └── robots.txt
├── astro.config.mjs
├── tsconfig.json
└── eslint.config.js

Part 1: Content Editing

How to Edit Content

When you want to edit any text or content on your site, follow these steps:

Step 1: Identify the content location

JSON-managed content: Check src/config/ for services, FAQ, team, menus, etc.
Section-specific content: Check src/components/sections/[SectionName].astro
Page content: Check src/pages/[page-name]/index.astro

Step 2: Search for the text Use your code editor’s search function (Cmd/Ctrl + Shift + F) to find the exact text you want to change.

Step 3: Edit and save

For JSON files: Edit the value and save
For .astro files: Edit the text directly in the HTML section

Example: Editing the Hero catchphrase

Search for the current text (e.g., “体験をデザインし”)
Find it in src/components/sections/Hero.astro (lines 13, 17)
Edit the <span> content:

<h1 class="hero-title">
  <span class="hero-title-line fade" data-animate data-animate-delay="0">
    Your new catchphrase here
  </span>
  <br />
  <span class="hero-title-line fade" data-animate data-animate-delay="200">
    Second line here
  </span>
</h1>

Update Brand Colors

Edit src/styles/tokens.css:

:root {
  --c-primary: #your-color; /* Main brand color */
  --c-primary-light: #your-color; /* Light version */
  --c-primary-dark: #your-color; /* Dark version */
}

JSON Configuration Reference

All content is managed through JSON files in src/config/.

Common configuration files:

site.config.json - Site info, SEO, company details
menu.json or menu.config.json - Navigation menus (filename varies by theme)
social.json or social.config.json - Social media links (filename varies by theme)
pages.config.json - Centrally manages page labels and paths (available in some themes)

In themes that include pages.config.json, menus are built by referencing page IDs in menu.config.json. To change a page’s label or path, edit pages.config.json.

Theme-specific configuration files:

Available configuration files vary by theme. Check the src/config/ directory for files such as:

Services/features (service.json, benefits.json, etc.)
Team/member information (team.json, etc.)
FAQ (faq.json, etc.)
Category settings (category.json, category.config.json, etc.)
Other theme-specific configurations

Tip: Open each JSON file to see the exact structure and available fields for each content type.

Edit Site Information

Edit src/config/site.config.json:

Basic info: title, description, company_name
SEO: og_image, favicon, themeColor
Language: lang (e.g., en, ja)
Company details (available in some themes): company section (address, phone, CEO, etc.)

Important: Also update site URL in astro.config.mjs for production.

Menu management varies by theme. Check src/config/ to determine which pattern your theme uses.

Pattern A: menu.json (themes without pages.config.json)

Paths and labels are written directly in the menu file.

main: Header navigation items
footer: Footer menu sections

Add dropdowns with a children array:

{
  "title": "Services",
  "path": "/services/",
  "children": [{ "title": "Web Development", "path": "/services/#web" }]
}

Pattern B: menu.config.json + pages.config.json (themes with pages.config.json)

Page info (labels and paths) is managed centrally in pages.config.json. Menus are built by referencing page IDs.

// pages.config.json — defines page labels and paths
[
  { "id": "services", "label": "Services", "href": "/services/" },
  { "id": "contact", "label": "Contact", "href": "/contact/" }
]

// menu.config.json — references pages by ID
{
  "main": ["services", "pricing", "about", "news", "faq", "contact"],
  "footer": [
    { "pageId": "services", "source": "services" },
    { "name": "Company", "menus": ["pricing", "about"] },
    { "name": "Support", "menus": ["faq", "contact"] }
  ]
}

To change a page label or path, edit pages.config.json, not menu.config.json.

Service detail dropdown (Pattern B)

Including "services" in main automatically generates a dropdown with links to individual service pages. Adding or removing service content files (in src/data/services/ etc.) is reflected in the menu automatically—no manual menu editing needed.

Replace Images (Logo, OGP etc…)

Common image files:

Logo: Replace src/assets/logo.svg
OGP image: Replace public/images/ogp.png (recommended size: 1200×630px)
Favicon: Replace public/images/favicon.svg

Theme-specific images:

Images used in sections vary by theme in terms of location and type.

How to find image files:

Check the src/assets/ directory
Open section components (src/components/sections/) to find image paths
Check image fields in JSON configuration files (src/config/)

Tip: Use your code editor’s search function (Cmd/Ctrl + Shift + F) to search for the image filename you want to replace and locate where it’s used.

Add/Remove Sections

To remove a section, delete its import and usage in page files:

---
- import Team from "@/components/sections/Team.astro";
import CTA from "@/components/sections/CTA.astro";
---

<Layout title="About">
-  <Team />
  <CTA />
</Layout>

To add a section, import and place it:

---
+ import Team from "@/components/sections/Team.astro";
import CTA from "@/components/sections/CTA.astro";
---

<Layout title="Services">
+  <Team />
  <CTA />
</Layout>

How to check available sections:

Open the src/components/sections/ directory to see available section components. Section types and features vary by theme.

Add Content (Content Collections)

Themes use Astro’s Content Collections to manage content. Available collection types vary by theme.

How to check available content:

Check the src/data/ or src/content/ directory for available collections (e.g., news/, works/, blog/, etc.)
Open src/content.config.ts to check each collection’s file format (Markdown or JSON) and schema

Adding content example:

Create files according to the file format used in each collection.

For Markdown files (.md):

---
title: "Article Title"
category: "category"
pubDate: 2025-01-20
# Other fields vary by collection
---

Content body here...

For JSON files (.json):

{
  "title": "Article Title",
  "category": "category",
  "pubDate": "2025-01-20"
}

Tip: Open existing files to check required fields and file format. File formats within a collection must be consistent.

Creating Markdown Pages (Available in Some Themes)

Some themes allow you to create pages by placing Markdown files (.md) directly in src/pages/.

Example: Terms of Service page (src/pages/terms.md)

---
layout: ../layouts/MarkdownLayout.astro
title: "Terms of Service"
---

# Terms of Service

Page content...

Features:

Content written in Markdown is automatically rendered as a page
Use the layout field in frontmatter to specify a dedicated layout (MarkdownLayout.astro, etc.)
Some themes include src/layouts/MarkdownLayout.astro

How to check:

Check if .md files exist in the src/pages/ directory
Check if src/layouts/MarkdownLayout.astro exists

For more details, see Astro’s Markdown Pages Guide.

Part 2: Developer Guide

Getting Started

Installation

npm install

Development

npm run dev

Opens at http://localhost:4321

Build & Deploy

npm run build    # Creates ./dist/
npm run preview  # Preview production build

Deploy the ./dist/ folder to Cloudflare Pages, Netlify, Vercel, or any static hosting provider.

Note: Deployment configuration and setup details vary by provider. Please refer to your hosting provider’s documentation for specific instructions:

Code Quality

npm run lint     # Lint code (auto-fix)
npm run format   # Format with Prettier
npm run check    # Lint + format check (no auto-fix)

Run npm run check before commits.

Settings Explained

In site.config.json > settings (available settings vary by theme):

{
  "pagination": 10, // Items per page (if Pagination.astro is available)
  "header_height": "74px", // Desktop header height (used in CSS)
  "header_height_mobile": "60px" // Mobile header height (used in CSS)
}

These values are used throughout the site:

header_height: Used as CSS custom properties in Layout.astro for scroll position adjustment and layout calculations
pagination: If Pagination.astro component is available, controls items per page for content listing pages

Image Guidelines

Use Astro’s Image component when:

Image path is static and known at build time
Importing directly: import heroImage from "@/assets/hero.jpg"

---
import { Image } from "astro:assets";
import heroImage from "@/assets/hero.jpg";
---

<Image src={heroImage} alt="Hero" width={1200} height={675} />

Use DynamicImage component when:

Image path is dynamic (from JSON/config)
Path is a string variable

The props structure varies by theme. Please check DynamicImage.astro directly.

Images in public/:

Reference with absolute paths: /images/ogp.png
No component needed: <img src="/images/ogp.png" alt="..." />
Note: Images in public/ are not optimized by Astro. For automatic optimization, use images in src/assets/ with the Image or DynamicImage components. See Astro Images Guide for more details.

Managing Sections

All sections are in src/components/sections/. To use a section:

Import it in your page
Place the component where needed
Pass props if required (check component file)

Many sections import JSON files from src/config/ to retrieve data. Open each section component to check its data source.

Icon Component (Available in Some Themes)

Some themes include an Icon.astro component. This component is a utility for displaying SVG icons.

Check availability:

Check if src/components/ui/Icon.astro exists.

Basic usage example:

---
import Icon from "@/components/ui/Icon.astro";
---

<Icon name="check" />
<Icon name="arrow-right" width={32} height={32} />

Props:

name (required): Icon name (check available icons in iconMap inside Icon.astro)
width (optional): Icon width (defaults to each icon’s original size)
height (optional): Icon height (defaults to each icon’s original size)

How to add new icons:

Place SVG icon file in appropriate directory under src/assets/
Open Icon.astro and import the icon
Add to iconMap object

---
import WriterIcon from "@/assets/features/ai-writer.svg"; // 1. Import
// ... other imports

const iconMap: Record<string, IconComponentProps> = {
  // ... existing icons
  "ai-writer": WriterIcon, // 2. Add to iconMap
  // ...
};
---

Now you can use <Icon name="ai-writer" />.

Form Customization

Edit src/components/sections/ContactForm.astro to modify form fields and behavior.

Form submission options (examples):

You can integrate with any form service or API of your choice. Here are some popular options:

Netlify Forms: Add netlify attribute to <form>
Formspree: Set action="https://formspree.io/f/YOUR_ID"
Custom API: Create your own endpoint
Other services: Any form handling service that accepts standard HTML forms

Choose the solution that best fits your needs and follow their integration guides.

Google Analytics

Add your GA4 measurement ID to src/config/site.config.json:

{
  "google": {
    "analytics": "G-YOUR-ACTUAL-ID"
  }
}

The GoogleAnalytics component in the layout will use this automatically.

Troubleshooting

Build Errors

“Cannot find module” or dependency errors:

rm -rf node_modules package-lock.json
npm install
npm run build

TypeScript errors:

Check src/types/index.d.ts for type definitions
Ensure JSON files match their TypeScript interfaces

Image Issues

Images not displaying:

Images in src/assets/: Must use Image or DynamicImage component
Images in public/: Use absolute paths (/images/file.jpg)
Check file paths are correct (case-sensitive)

DynamicImage error “does not exist in glob”:

Verify image path starts with /src/assets/
Check file extension is .svg, .jpg, .jpeg, .png, or .webp
Ensure file actually exists at that path

JSON Errors

Build fails with JSON parse error:

Validate JSON syntax at jsonlint.com
Check for missing/extra commas
Ensure all brackets/braces are closed
No trailing commas in arrays/objects

Dropdown not appearing:

Verify children array exists in menu item
Check JSON syntax is valid

Wrong active state:

Check path values match actual page routes
Paths should start with / and end with / for pages

Performance Issues

Slow build times:

Check image sizes (optimize large images)
Consider using WebP format

Large bundle size:

Audit unused sections and remove imports
Check for duplicate dependencies

Common Development Issues

Dev server not updating:

# Restart dev server
npm run dev

Pre-Deployment Checklist

Required Items

Pre-Launch Tests

Support

If you encounter any issues, bugs, or have questions about this theme, please don’t hesitate to contact us through our contact page. We’re here to help!

However, it does not provide lessons on HTML, CSS, Astro, or other programming languages.

License

You can read about the themes license on the license page.

Last updated: April 4, 2026

Documentation