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

> Discover how cangjie-skill automatically generates INDEX.md with Mermaid citation graphs using Jinja2 templates and Zettelkasten linking to visualize skill relationships like depends-on, contrasts-with, and composes-with.

- Repository: [kangarooking/cangjie-skill](https://github.com/kangarooking/cangjie-skill)
- Tags: internals
- Published: 2026-08-16

---

**The [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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:

```markdown

## 引用图

```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`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) with a fully populated Mermaid citation graph.

## Output Contents

The generated [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/BOOK_OVERVIEW.md), [`DIGEST.md`](https://github.com/kangarooking/cangjie-skill/blob/main/DIGEST.md), [`GLOSSARY.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/05-stage3-zettelkasten.md) | Documents the generation methodology |
| [`README.md`](https://github.com/kangarooking/cangjie-skill/blob/main/README.md) | References the process in the "Zettelkasten Linking" section |
| `books/<slug>/metadata.json` | Input data source for template rendering |

## Summary

- The [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) with Mermaid citation graphs is generated during the **Zettelkasten linking stage** as documented in [`methodology/05-stage3-zettelkasten.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) files to extract dependency metadata and generates interconnected documentation including the [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) files throughout the repository.