Astro Content

astro-content

Create Astro/​Starlight MDX content pages.

Trigger Examples

• "Write a new article"
• "Add an article to Tech category"
• "Create a blog post"
• "Add an MDX page"

Directory Structure

app/​src/​content/​docs/
├── about-me/          # About Me section
│   └── overview.mdx
├── tech/              # Tech articles
│   └── *.mdx
└── life/              # Life articles
    └── *.mdx

Execution Flow

0. Wall-Hitting Phase (Before Writing)

Before creating files, have a conversation with the user to clarify the article's direction:

1. Clarify the core message

   • Ask: "What do you want readers to take away?"
   • Identify the single most important point

2. Dig into experiences and episodes

   • Ask for concrete stories, failures, and learnings
   • Extract raw, unpolished details (these become authentic content)

3. Decide writing style early

   • Japanese: Confirm「だ・である調」vs「ですます調」before writing
   • English: Confirm formal vs conversational tone

4. Verify title-content alignment

   • Ensure the title matches the core message
   • If the content evolves, revisit the title

1. Confirm Category

Ask user for category:

2. Gather Article Information

Confirm the following:

• Title: Article title
• Description: One-sentence summary
• Slug: URL path (e.g., tech/​genkit-intro → /​tech/​genkit-intro/)
• Draft: Whether it's a draft (default: false)

3. Create MDX File

File path: app/​src/​content/​docs/​{category}/​{slug}.mdx

Frontmatter template:

---
title: <title>
description: <description>
draft: true  # Only if draft
---

With hero image:

---
title: <title>
description: <description>
hero:
  tagline: <subtitle>
  image:
    alt: <image description>
    file: ../​../​../​assets/<image-file>
---

4. Update sidebar.ts

Add new article to app/​src/​sidebar.ts:

{
  label: "Tech",
  items: [
    { label: "<Article Title>", slug: "tech/<slug>" },
  ],
},

5. Assets (Optional)

If using images:

1. Place image in app/​src/​assets/
2. Import and use in MDX:

import myImage from '../​../​../​assets/​my-image.png';

<img src={myImage.src} alt="Description" style="..." />

Content Guidelines

1. Language: English or Japanese (follow user preference)
2. Markdown: Use GitHub Flavored Markdown
3. Headings: Start with ## (# is auto-generated from title by Starlight)
4. Lists: Use bullet points for readability
5. Code blocks: Always specify language (typescript, bash, etc.)
6. Emoji: Use sparingly (only when user explicitly requests)

Avoiding AI-like Writing

Common patterns that make articles feel "AI-generated" — avoid these:

Headings

• Avoid: 「転機：〜」「結論：〜」「まとめ」 (feels formulaic)
• Better: Simple, direct headings that flow naturally from content

Structure

• Avoid: Overly organized tables summarizing points (feels forced)
• Better: Let the narrative carry the message; tables only when genuinely helpful

Introductions

• Avoid: Starting with a dialogue or rhetorical question that feels staged
• Better: Jump into the topic directly or share a brief personal context

Conclusions

• Avoid: Abrupt transition to "## 結論" with bullet-point summaries
• Better: Use a horizontal rule (---) and let the closing flow naturally from the content

Tone

• Avoid: Overly balanced statements ("〜かもしれない" everywhere)
• Better: Take a stance when you have conviction; acknowledge uncertainty honestly when you don't

Key principle

If a section feels "too neat" or "too organized," it probably needs more raw, human detail. Ask the user for specific episodes, failures, or emotions to make it authentic.

Post-Creation Verification

After creation, suggest:

cd app && npm run build && npm run lint && npm run typecheck

Verify build succeeds.