astro-content

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

astro-content

Astro/Starlight MDX内容页面创建

Create Astro/Starlight MDX content pages.

创建Astro/Starlight MDX内容页面。

Trigger Examples

触发示例

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

“撰写新文章”
“向技术分类添加文章”
“创建博客文章”
“添加MDX页面”

Directory Structure

目录结构

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

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)

0. 前期沟通阶段（撰写前）

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

Clarify the core message
- Ask: "What do you want readers to take away?"
- Identify the single most important point
Dig into experiences and episodes
- Ask for concrete stories, failures, and learnings
- Extract raw, unpolished details (these become authentic content)
Decide writing style early
- Japanese: Confirm「だ・である調」vs「ですます調」before writing
- English: Confirm formal vs conversational tone
Verify title-content alignment
- Ensure the title matches the core message
- If the content evolves, revisit the title

在创建文件前，需与用户沟通以明确文章方向：

明确核心主旨
- 提问：“你希望读者从文章中获得什么？”
- 确定最核心的要点
深挖经历与具体事例
- 询问具体的故事、失败经历和经验教训
- 提取原始、未经修饰的细节（这些会成为真实可信的内容）
提前确定写作风格
- 日语：撰写前确认「だ・である調」（简体）与「ですます調」（敬体）的使用
- 英语：确认正式语气还是口语化语气
验证标题与内容的匹配度
- 确保标题与核心主旨相符
- 如果内容有所调整，需重新审视标题

1. Confirm Category

1. 确认分类

Ask user for category:

Category	Purpose
tech	Technical articles (Cloud, AI, DevOps, Architecture, etc.)
life	Lifestyle, hobbies, journals, etc.

向用户确认分类：

分类	用途
tech	技术类文章（云服务、AI、DevOps、架构等）
life	生活类文章（生活方式、爱好、日志等）

2. Gather Article Information

2. 收集文章信息

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)

确认以下信息：

标题：文章标题
描述：一句话摘要
Slug：URL路径（例如：
```
tech/genkit-intro
```
→
```
/tech/genkit-intro/
```
）
草稿状态：是否为草稿（默认：false）

3. Create MDX File

3. 创建MDX文件

File path:

app/src/content/docs/{category}/{slug}.mdx

Frontmatter template:

yaml

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

With hero image:

yaml

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

文件路径：

app/src/content/docs/{category}/{slug}.mdx

Frontmatter模板:

yaml

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

带封面图的模板:

yaml

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

4. Update sidebar.ts

4. 更新sidebar.ts

Add new article to

app/src/sidebar.ts

typescript

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

将新文章添加至

app/src/sidebar.ts

typescript

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

5. Assets (Optional)

5. 资源文件（可选）

If using images:

Place image in
```
app/src/assets/
```
Import and use in MDX:

mdx

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

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

如果使用图片：

将图片放入
```
app/src/assets/
```
目录
在MDX中导入并使用：

mdx

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

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

Content Guidelines

内容规范

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

语言：英语或日语（遵循用户偏好）
Markdown：使用GitHub风格的Markdown
标题层级：从
```
##
```
开始（
```
#
```
会由Starlight根据文章标题自动生成）
列表：使用项目符号提升可读性
代码块：务必指定语言类型（如
```
typescript
```
、
```
bash
```
等）
表情符号：谨慎使用（仅在用户明确要求时使用）

Avoiding AI-like Writing

避免AI式写作

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

以下是让文章显得像AI生成的常见模式，请避免：

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:

bash

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

Verify build succeeds.

创建完成后，建议执行以下命令：

bash

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

验证构建是否成功。