Table Code Reference

Table Code Reference turns stable IDs stored in Markdown table rows into autocompleteable, clickable inline references. It can also export every indexed row into a categorized JSON tree for use by game engines, static-site generators, or other data pipelines.

Features

• Configurable start and end delimiters. The default syntax is @bA1 .
• Live autocomplete by ID or display name, finalized-only by default, with a configurable result limit.
• Automatic index refresh from the current editor buffer while table IDs are being added or changed.
• Clickable references in Reading view and Live Preview that jump to the source table row.
• Column offsets such as @cA1[1]-2 and nested references with cycle/depth protection.
• Scope control: only index selected Vault folders and their descendants.
• Diagnostics for duplicate IDs, missing columns, unresolved references, cycles, and temporary inferred IDs.
• Categorized JSON export with a global lookup index and raw/resolved field values.

ID convention

The default convention combines three sources:

1. A lowercase prefix on a parent directory, such as b.heroes -> b.
2. An uppercase prefix on the Markdown file, such as A.faction.md -> A.
3. A local value in the table's 编号 or 代码编号 column, such as 1.

The resulting full ID is bA1. A table may also store the complete ID directly. Header aliases, source folders, finalization markers, and label columns are configurable.

If Infer missing IDs is enabled, rows with a display name but an empty ID cell receive a temporary ID based on their order among valid data rows in that file. You can restrict inference to selected lowercase category codes. Selecting an inferred suggestion writes its local ID back into that source cell; diagnostics and JSON output continue to mark unselected inferred IDs. If a temporary ID conflicts with an explicit ID, the explicit source value always wins.

Reference syntax

With the default start symbol @ and end symbol (a space):

@cA1[1] 
@cA1[1]-1 
@{cA1[1]-2} 

• No suffix or -0 resolves to the configured label column.
• -1 resolves to the first column to the right of the label, and so on.
• Start and end delimiters are consumed and are not displayed.
• The braced form remains available for ambiguous text.
• Doubling the start symbol escapes a reference, for example @@bA1 .

Referenced cells may contain other references. Rendering stops at the configured maximum depth and reports cycles.

Autocomplete

Type the start symbol in a Markdown file inside a configured source folder. Continue typing to filter the bounded result list, for example @a or @hero name. By default, draft rows are excluded from this menu without being removed from the index or JSON export. Type - after an ID, such as @cA1[1]-, to browse its label column and every column to the right. Selecting a result by mouse or keyboard inserts the complete reference, including the selected column offset and end delimiter, and closes the menu.

If there are no matches, the menu explains whether the index is empty or the query has no result. Run Rebuild table reference index from the command palette after changing a large set of source files.

Categorized JSON export

Run 导出分类 JSON 数据（Godot 缓存） from the command palette. The default output folder is data/json/design_cache inside the Vault. Exporting is manual; editing a note does not write JSON automatically.

The exporter creates:

data/json/design_cache/
  _index.json
  <category>/<group>.json

Each group file is a JSON array. Every record contains its stable ID, display name, finalization state, inferred-ID flag, source location and hash, raw Markdown cells, fully resolved plain-text cells, and referenced IDs. _index.json stores schema/version metadata, diagnostics, managed file names, and an ID-to-file/index lookup.

Use Export path aliases to make codes match an existing data tree:

a=traits
aA=basic_term
b=heroes
bA=first_faction
e=cards/spell_card

A one-letter key maps a category directory. A two-letter key maps a group file name within that category. Paths must be relative and may contain only safe path segments. Unmapped codes fall back to their literal letters.

The output is a source-data cache rather than a promise to match every engine's runtime schema. A game can load _index.json for stable foreign-key lookup, then map the exported resolved fields into its own runtime resources. Dynamic combat state should remain separate from these immutable definitions.

Installation for development

npm install
npm test
npm run build

For manual installation, copy main.js, manifest.json, and styles.css into:

<Vault>/.obsidian/plugins/table-code-reference/

Then reload Obsidian and enable Table Code Reference under Community plugins.

Privacy and data access

The plugin works offline. It has no telemetry, ads, account requirement, or network requests. It reads Markdown files only inside the source folders you configure and writes JSON only when you run the export command, inside the Vault-relative export folder you configure.

中文速览

本插件把 Markdown 表格中的稳定编号变成可自动补全、可点击跳转、可嵌套的内联引用。默认输入 @编号+空格，下拉菜单只显示已定稿行；输入 @编号- 可继续选择具体列。选择推导出的临时编号后，插件会把局部编号写回源表的空编号单元格。开始符、结束符、适用目录、编号列名和名称列名均可设置。

在命令面板运行“导出分类 JSON 数据”，会生成 _index.json 与按类别/分组拆分的 JSON 数组文件。缺失编号可选择按有效数据行顺序临时推导，但正式项目仍建议把编号写回表格，避免排序后编号变化。

License

MIT