Kanji Index

Format: {5-digit}_{onyomi}_{kunyomi}_{gloss}

• 5-digit: Sequential number (00001, 00002, ...)
• onyomi: Most common on'yomi in romaji (or "none")
• kunyomi: Most common kun'yomi in romaji without okurigana (or "none")
• gloss: Single English word for primary meaning

Examples

Romaji Rules

• Long vowels: "ou" not "ō" (e.g., 高 → "kou")
• Voiced: "ga", "za", "da", "ba" (e.g., 学 → "gaku")
• No okurigana in kun'yomi (e.g., 高い → "taka", not "takai")

Assigning New Kanji IDs

When new entries introduce kanji not in kanji_list.json:

1. Detect new kanji:

   python3 build/update_kanji_index.py --check-new
   

2. Assign readings and gloss using your knowledge:

   • Most common on'yomi
   • Most common kun'yomi (without okurigana)
   • Single-word English gloss

3. Update kanji_list.json:

   {
     "新": {
       "kanji_id": "00123_shin_atara_new",
       "onyomi": "shin",
       "kunyomi": "atara",
       "gloss": "new"
     }
   }
   

4. Rebuild:

   python3 build/build_flat.py
   

Common Tasks

Check for New Kanji

python3 build/update_kanji_index.py --check-new

Rebuild All Kanji JSON Files

python3 build/update_kanji_index.py --rebuild-all

Rebuild Kanji HTML Pages

python3 build/build_kanji_html.py

Full Site Build (includes kanji)

python3 build/build_flat.py

Troubleshooting

"Warning: X kanji need IDs assigned"

New kanji were found in entries. Assign IDs manually:

1. Run --check-new to see the full list
2. For each kanji, determine on'yomi, kun'yomi, gloss
3. Add to kanji/kanji_list.json
4. Rebuild

Missing kanji index page

Check that:

1. Kanji is in kanji/kanji_list.json
2. JSON file exists: kanji/{kanji_id}.json
3. Run python3 build/build_kanji_html.py

Kanji link not appearing in headword

Check that:

1. Kanji is in kanji/kanji_list.json
2. Entry HTML was rebuilt after kanji was added

Entry count wrong on kanji page

Rebuild the kanji JSON file:

python3 build/update_kanji_index.py --rebuild-all
python3 build/build_kanji_html.py

File Formats

kanji_list.json

{
  "metadata": {
    "description": "Index mapping kanji characters to their kanji index IDs",
    "generated": "2026-01-22T10:30:00Z",
    "total_kanji": 1500
  },
  "kanji": {
    "人": {
      "kanji_id": "00001_jin_hito_person",
      "onyomi": "jin",
      "kunyomi": "hito",
      "gloss": "person"
    }
  }
}

Individual kanji JSON

{
  "metadata": {
    "kanji": "人",
    "kanji_id": "00001_jin_hito_person",
    "onyomi": "jin",
    "kunyomi": "hito",
    "gloss": "person",
    "entry_count": 245,
    "generated": "2026-01-22T10:30:00Z"
  },
  "entries": [
    {
      "id": "01234_akunin",
      "headword": "{悪|あく}{人|にん}",
      "reading": "あくにん",
      "gloss": "villain, bad person"
    }
  ]
}

Design Decisions

Why invisible links?

• Preserves clean headword appearance
• Users discover feature through tooltip
• No visual clutter

Why romaji in kanji IDs?

• ASCII-safe file names
• Human-readable
• Easy to search and sort

Why sort by reading?

• Natural Japanese ordering (gojuon)
• Consistent with how dictionaries organize entries
• Helps users find related words