Full Guide Before Editing

The path shown at the top of this page is the real repository file you are about to edit.

Read that path first and classify it:

• src/content/artists/...: artist, creator, group, and similar entry pages
• src/content/projects/...: project and derived-plan pages
• src/content/logs/...: observation logs, news, and timeline updates
• src/content/site/...: homepage labels, navigation, footer copy, section text
• src/content/contribute/...: the contributor guide pages themselves

If you are fixing copy, adding facts, updating metadata, or adjusting images, that is usually a content edit and should stay inside src/content/.

The most important rule for beginners is:

Most wiki contributions change content files, not page code.

So start by asking “which content file should this live in?” rather than “which component should I change?”

The most common shapes are:

src/content/artists/<category>/<entry>/<locale>.md
src/content/projects/<category>/<project>/<locale>.md
src/content/logs/<year>/<record>/<locale>.md

The homepage sections 01. DATABASE, 02. PROTOCOLS, and 03. LOG are designed to render from this structure automatically.

Each entry file has two parts: frontmatter and body content.

The frontmatter is the block between the opening --- lines. It stores structured metadata. The body comes after the second --- and contains the actual wiki writing.

---
locale: "en"
translationKey: "kaf"
name: "KAF"
romanizedName: "KAF"
statusLabel: "STATUS"
status: "ACTIVE"
image: "https://example.com/image.jpg"
---

The first fields to understand are:

• locale
• translationKey
• name
• romanizedName
• statusLabel and status
• image

translationKey must remain identical across the localized files, or the site will stop treating them as one entry.

Artist entries can also include theme, which controls the article theme color and the palette panel in the infobox.

theme:
  name: "KAF Bloom"
  accentColor: "#F29AC2"
  mutedColor: "#E63145"
  surfaceColor: "#111321"
  highlightColor: "#FFF6FA"
  palette:
    - label: "KAF Pink"
      value: "#F29AC2"
    - label: "Bloom Red"
      value: "#E63145"

Do not invent colors casually. Prefer official artist pages, official key visuals, official album covers, or character material. Put the strongest recognition color in accentColor, and keep surfaceColor dark enough for comfortable reading.

The site supports three locale routes:

/zh/  Chinese, default locale
/ja/  Japanese
/en/  English

So when you add a new translatable record, the safest pattern is:

• create zh.md
• create ja.md
• create en.md

Even if the body text is incomplete, try to create the full structure from the start.

The article body is ordinary Markdown. You can use:

• paragraphs
• lists
• bold text
• blockquotes
• inline code and code blocks
• tables
• links

When in doubt, start from the most stable information:

1. basic identity details
2. debut timing or project affiliation
3. official links or source notes
4. then fuller descriptive paragraphs

Avoid these mistakes:

• editing dist/, .astro/, or node_modules/
• moving large wiki passages into implementation files
• filling empty sections with placeholder copy

After you use the final action on this page, GitHub will usually open the web editor for the current file.

Once you are there:

1. confirm the file path still matches the one shown here
2. edit the frontmatter or article body
3. scroll to the commit form
4. write a short, clear commit message

If GitHub asks how to save the change:

• already on your own branch: commit directly there
• not on your own branch: choose Create a new branch for this commit and start a pull request

This repository uses a GitHub Pull Request workflow.

A normal path looks like this:

1. edit the file
2. commit to your branch
3. open a Pull Request
4. wait for CI
5. address review comments or failing checks

The core validation commands are:

pnpm test
pnpm check
pnpm build

If CI fails, keep working on the same branch. You do not need a new PR.

The usual mistakes are:

• editing the wrong file path
• forgetting one of the locale files
• letting translationKey drift across locales
• mixing content edits with implementation changes
• committing generated output
• using placeholder text instead of real content

Quick self-check:

1. Am I editing something inside src/content/...?
2. Have I considered the localized files?
3. Am I changing content, not implementation?
4. Would another maintainer immediately understand what changed?

The important thing on this page is the target path above.

In this repo, you are editing a concrete src/content/... file, not “a page” in the abstract. Content is the primary data source.

Quick classification:

• src/content/artists/...: DATABASE entries
• src/content/projects/...: PROTOCOLS cards and project pages
• src/content/logs/...: LOG news-style records
• src/content/site/...: homepage and chrome copy

The main constraints right now are:

1. content and implementation are separated
2. the site runs in three locales
3. homepage sections try to render from folder structure
4. metadata is mostly automated, with seo.* as explicit overrides

In practice, content editing should prioritize:

• correct folder placement
• stable translationKey
• schema-valid frontmatter
• preserving auto-generated category and entry behavior

Primary content model:

src/content/artists/<category>/<entry>/<locale>.md
src/content/projects/<category>/<project>/<locale>.md
src/content/logs/<year>/<record>/<locale>.md

Common actions:

• add a category: create a first-level folder
• add an entry: create a second-level folder plus localized files
• tune ordering: use categoryOrder / itemOrder
• tune display labels: use categoryTitle / categorySubtitle
• override SEO precisely: use seo.title / seo.description / seo.image

You do not need every field on every edit, but these are the most relevant:

• locale
• translationKey
• name
• romanizedName
• image
• statusLabel / status
• categoryTitle / categorySubtitle
• categoryOrder / itemOrder
• theme.*
• seo.*

For localized entries:

• keep translationKey identical
• prefer all three locale files to exist together
• the bodies can vary in completeness, but the structure should stay aligned
• keep theme color values synchronized across locales, while localizing palette.label

The shortest safe path is:

1. open the GitHub editor for the current file
2. edit frontmatter and/or Markdown body
3. commit to your branch
4. open a PR
5. let CI run

If GitHub asks about branch strategy:

• already on your own branch: commit directly
• not on your own branch: create a new branch and start the PR

The three checks worth keeping in your head are:

pnpm test
pnpm check
pnpm build

They broadly cover:

• content structure and i18n assumptions
• Astro diagnostics and collection schema
• static build integrity

Common failure sources:

• YAML/frontmatter indentation errors
• mismatched translationKey or locale values
• directory shape not matching the auto-render assumptions
• mixing content changes with implementation edits