How the INDEX.md with Mermaid Citation Graphs Is Generated in cangjie-skill

The INDEX.md files with Mermaid citation graphs are generated during the Zettelkasten linking stage using a Jinja2 template that renders skill metadata into a graph LR diagram showing three relationship types: depends-on, contrasts-with, and composes-with.

The cangjie-skill repository automates the creation of structured book indexes that visualize skill dependencies through interactive Mermaid diagrams. This generation process, documented in methodology/05-stage3-zettelkasten.md, transforms raw skill metadata into a human-readable catalog with embedded citation graphs.

The Three-Stage Generation Pipeline

Stage 1: Collect Book-Level and Skill Metadata

The process begins by aggregating data from throughout the repository. The build pipeline gathers:

• Book metadata: author, publication year, total skill count
• Per-skill metadata: slug, one-line description, and dependency relationships declared in individual SKILL.md files

This collection happens during the Zettelkasten linking stage, which establishes connections between discrete knowledge units.

Stage 2: Build the Mermaid Graph Structure

While iterating over skill metadata, the generation script constructs a Mermaid graph LR (left-to-right) block that expresses three semantic relationship types:

• --> — depends-on
• -.-> — contrasts-with
• === — composes-with

The generated block is inserted into the "引用图" (Citation Graph) section of the template, occupying lines 30-42 of templates/INDEX.md.template.

Stage 3: Render the Jinja2 Template

The final step uses Python's jinja2 engine to populate templates/INDEX.md.template with the collected data. Placeholders like {{BOOK_TITLE}}, {{skill-slug-1}}, and {{skill-a}} are replaced with actual values, producing the finished books/<slug>/INDEX.md file.

Template Structure and Mermaid Syntax

The templates/INDEX.md.template defines the exact structure of the output. Here is the Mermaid section from that template:

## 引用图

```mermaid
graph LR
    A[skill-a] -->|depends-on| B[skill-b]
    A -.->|contrasts-with| C[skill-c]
    B ===>|composes-with| D[skill-d]

图例:

• --> depends-on
• -.-> contrasts-with
• ===> composes-with

The resulting diagram provides immediate visual insight into how skills relate to one another—critical for navigating complex technical domains.

## Rendering Implementation

According to the `cangjie-skill` source code, the rendering logic uses a small Python script embedded in the build pipeline. The same logic powers the CI workflow that creates `books/<slug>/INDEX.md`. Here is the typical rendering pattern:

```python
import pathlib, json
from jinja2 import Environment, FileSystemLoader

# load collected metadata (generated earlier by the Zettelkasten stage)

data = json.load(open('books/<slug>/metadata.json'))

env = Environment(loader=FileSystemLoader('templates'))
template = env.get_template('INDEX.md.template')
output = template.render(**data)

pathlib.Path('books/<slug>/INDEX.md').write_text(output)

Running this script after the Zettelkasten analysis produces the final INDEX.md with a fully populated Mermaid citation graph.

Output Contents

The generated INDEX.md file contains:

• A human-readable skill catalog
• A ready-to-render Mermaid citation graph
• Installation hints for the target book
• Links to auxiliary artifacts: BOOK_OVERVIEW.md, DIGEST.md, GLOSSARY.md

Key Files and Their Roles

File	Purpose
templates/INDEX.md.template	Jinja2 template defining structure and Mermaid block placement
methodology/05-stage3-zettelkasten.md	Documents the generation methodology
README.md	References the process in the "Zettelkasten Linking" section
books/<slug>/metadata.json	Input data source for template rendering

Summary

• The INDEX.md with Mermaid citation graphs is generated during the Zettelkasten linking stage as documented in methodology/05-stage3-zettelkasten.md
• Jinja2 templating powers the transformation from metadata to markdown via templates/INDEX.md.template
• Three relationship types—depends-on, contrasts-with, and composes-with—are rendered as Mermaid graph LR syntax
• The build pipeline embeds Python rendering logic that also runs in CI workflows
• Output files include complete navigation links to auxiliary documentation

Frequently Asked Questions

What is the Zettelkasten linking stage?

The Zettelkasten linking stage is the third phase of the cangjie-skill methodology where discrete skill notes are connected through explicit relationships. During this stage, the system analyzes SKILL.md files to extract dependency metadata and generates interconnected documentation including the INDEX.md citation graphs.

Why does the template use Chinese section headers like "引用图"?

The "引用图" (citation graph) header reflects the repository's bilingual design. The Mermaid diagram serves as a universal visual language, while the Chinese labels align with the project's origin and primary audience. The legend below the diagram ensures clarity for all readers regardless of language.

Can I customize the relationship types in the Mermaid graph?

The three relationship types—-->, -.->, and ===—are hardcoded in the template structure at lines 30-42 of templates/INDEX.md.template. Adding new relationship types would require modifying both the template and the metadata collection logic in the Zettelkasten stage pipeline.

Where does the metadata.json file come from?

The metadata.json file is produced earlier in the build pipeline during skill ingestion and analysis. It aggregates book-level information and per-skill metadata including slugs, descriptions, and declared relationships parsed from individual SKILL.md files throughout the repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}