Code Block Parameter Fold

by zonvon
5
4
3
2
1
Score: 50/100
New Plugin

Description

About Obsidian's plugin

Reviews

No reviews yet.

Stats

0
stars
13
downloads
0
forks
0
days
0
days
0
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
17
commits

Latest Version

15 hours ago

Changelog

Fold name[options] inside code blocks into a clickable tag — expand it when you need the details, or switch to a hover popup that lists every option with its comment.

3.4.2 变更

  • 标注为仅桌面端(isDesktopOnly: true)。插件本身没有用到桌面专属 API,但没有在移动端实测过, 与其对外声称支持、让用户踩坑,不如先如实标注。将来实测通过后改回 false 即可。

3.4.1 变更

  • 插件显示名改为 Code Block Parameter Fold,description 改为英文,为提交社区列表做准备。
  • id(code-block-context-fold)保持不变,已装实例、设置和折叠记录都不受影响;界面文案仍跟随 Obsidian 的语言。

两种显示方式

  • 普通折叠:Cull 选项[back/Front/Off] 只显示带下划线的 Cull 选项,[内容] 收起来,点一下展开。
  • 选项悬浮弹窗:折叠成药丸状的 Cull 选项 ▾,悬停浮出选项列表,再移到某个选项上浮出它的注释。

选项格式

一行一个选项,// 之后是注释:

混合模式[
  Normal//正常混合
  Add//相加,越高越亮
]

_ 不需要转义,_MainTex_ST、UNITY_OBJECT_TO_WORLD 这些名字可以直接写。[ ] 仍是结构字符。

怎么用

  1. 在一个代码块里选中完整的 参数[内容](支持多行、支持嵌套方括号),右键折叠。
  2. 想批量录入选项:右键 → 插入参数选项,填名称、逐个加「选项 + 注释」,保存。
  3. 在标签上右键可以切换显示方式、编辑选项、展开或取消折叠。
  4. 折叠多了想盘点:命令面板 → 打开折叠总览(支持搜索)。

折叠位置会记在插件数据里,重开笔记自动恢复;笔记重命名时记录跟着迁移。

安装

  1. 下载 manifest.json、main.js、styles.css(或 code-block-context-fold-3.4.1.zip 解压)。
  2. 放到 <你的库>/.obsidian/plugins/code-block-context-fold/,三个文件平铺,不要多套一层文件夹。
  3. 设置 → 第三方插件 → 关闭安全模式 → 刷新 → 启用 Code Block Parameter Fold。

插件不绑定任何库,每个库各自保存自己的折叠记录。

已知限制

  • 阅读视图里的展开状态只影响当前渲染,不会写回编辑视图。
  • 两个内容完全相同的代码块会被按出现顺序各自对应。
  • 方括号 [ ] 不能出现在参数名、选项名或注释里。
  • 同一段文本出现多次且锚点无法区分时,会放弃恢复而不是猜位置。

许可证

GPL-3.0-or-later。

README file from

Github

English | 简体中文

Code Block Parameter Fold

Fold a long name[options] inside a code block into one clickable tag — expand it when you need the details, or switch to a hover popup that lists every option together with its comment.

It is built for anything shaped like a name plus a long list of accepted values: shader properties, engine settings, CLI flags, enum values — as long as you can write it as name[content].

Repository: https://github.com/zhongxiaguchen/code-block-context-fold · Latest: 3.4.2

two display modes

Features

  • Plain fold — Cull 选项[back/Front/Off] collapses to an underlined Cull 选项; click to expand, click again to collapse.
  • Options popup — collapses to a Cull 选项 ▾ pill; hover to list the options, hover an option to see its comment.
  • Context menu — right-click a tag to edit its options, switch display mode, expand/collapse, or remove the fold.
  • Command palette — fold the current selection, remove the fold at the cursor, open the fold overview.
  • Editing view and reading view — folds survive switching to reading view and exporting to PDF; tags stay clickable there.
  • Positions stick — folds are restored when a note is reopened, and they follow the note when you rename it.
  • Settings and an overview — pick the default display mode, turn reading-view folding on/off, and browse a searchable list of every fold in the vault.
  • English and Chinese UI — follows Obsidian's language setting; other languages fall back to English.

Install

Manual (works in any vault)

  1. Download manifest.json, main.js and styles.css from Releases (or grab code-block-context-fold-3.4.2.zip and unzip it).
  2. Create the folder <your vault>/.obsidian/plugins/code-block-context-fold/.
  3. Put the three files directly inside it — do not nest them in another folder.
  4. Obsidian → Settings → Community plugins → turn off Safe mode → reload → enable the plugin.

The plugin is not tied to any vault: each vault keeps its own fold data.

Development install

node scripts/deploy.mjs --vault "/path/to/vault"

Copies the three build outputs only; your vault's data.json is left untouched.

Usage

Fold something you already wrote

Select a complete name[content] inside a code block — multi-line selections and nested brackets both work — then right-click → the fold command, or use the command palette.

Insert options with a form

  1. Put the cursor inside a code block (outside one is fine too — the plugin wraps it in a code fence tagged text).
  2. Command palette or context menu → the insert command.
  3. Name the parameter, add each option with an optional comment, save.

The generated text looks like this:

混合模式[
  Normal//正常混合
  Add//相加,越高越亮
]
  • One option per line; everything after // is a comment.
  • Parameter names and option values cannot contain brackets or newlines. Underscores, =, + and so on are all fine.
  • Comments are single-line: line breaks in the form are flattened, because a newline now separates options.

Two display modes

Right-click a tag → switch between plain fold and options popup. Switching only changes the rendering; your note text is never modified.

Settings and overview

Settings → Community plugins → this plugin:

  • Default display mode — which form new folds take. Existing folds can still be switched individually via right-click.
  • Fold in reading view — turn it off to keep reading view and PDF export showing the original text.
  • Fold overview — every fold in the vault, grouped by note. Click a note to jump there, delete a single fold, or clean up records pointing at deleted notes. The search box filters by tag, option text, or note name.

The overview is also available from the ribbon icon and from the command palette.

Data and privacy

No network access, no telemetry, no analytics. The plugin does exactly two things: it reads notes from your vault, and it writes fold positions to a local JSON file.

Fold records live in .obsidian/plugins/code-block-context-fold/data.json:

  • They store vault-relative paths plus anchors used to relocate a fold (code block language, block index, line hint, 64 characters of surrounding context).
  • Because those anchors contain fragments of your note text, the file is listed in .gitignore. Do not commit or share it.
  • Installing into another vault starts from scratch; nothing leaks between vaults.

Known limitations

  • Expanding inside reading view is one-off — it only affects the current render and is not written back to the editor.
  • Reading view uses the same anchor matching as the editor — it no longer requires an exact match, so edited content is still found. The cost is that each render reads the note source once (cached per file, invalidated on change). Two code blocks with identical content are matched by order of appearance.
  • Brackets [ ] are structural and cannot appear in parameter names, option values, or comments.
  • When the same text appears several times and the anchors cannot tell the occurrences apart, the plugin gives up rather than guessing a position.
  • Desktop only for now. The plugin does not use desktop-specific APIs, but it has not been tested on mobile, so the manifest declares isDesktopOnly: true.

Development

Requires Node.js ≥ 22.8.

npm run build          # zero-dependency bundle: src/ → main.js
npm run build:esbuild  # bundle with esbuild (after npm i)
npm test               # unit tests (Node's built-in runner)
npm run release        # validate + build + test + zip

npm run build uses scripts/build.mjs, a small bundler that only inlines relative require calls, so a fresh clone builds without installing anything. obsidian and @codemirror/* always stay external and are provided by the Obsidian runtime.

Layout

src/
  main.js                 lifecycle, context menus, commands, data IO
  state.js                shared plugin instance and right-click context
  editor/blocks.js        code fence scanning
  editor/selection.js     selection → fold region
  editor/anchor.js        anchor capture
  editor/recover.js       relocating folds after edits
  editor/decorations.js   CodeMirror StateField, decorations, mouse handling
  editor/text-range.js    range lookup across text nodes (reading view)
  reading/source.js       source snapshot and anchor projection for reading view
  reading/render.js       fold rendering in reading view / export
  format/parameters.js    parse and serialize parameter expressions
  settings/defaults.js    default settings and normalization
  settings/overview.js    data projection for the overview
  ui/options-dom.js       pill and hover panel DOM (shared by editor and reading view)
  ui/options-widget.js    CodeMirror widget wrapper
  ui/setup-modal.js       option editor form
  ui/settings-tab.js      settings page
  ui/overview-modal.js    fold overview
  util/{id,text}.js       small helpers
scripts/
  build.mjs               zero-dependency bundler
  deploy.mjs              install into any vault
  migrate-legacy-format.mjs  one-off migration from the 2.x format
  release.mjs             validation + zip
test/                     unit tests
docs/                     README images and recording guide
.github/workflows/        builds and publishes on tag push
main.js                   build output (committed for direct install)

Releasing

See RELEASING.md. The short version:

  1. Bump version in manifest.json and package.json, and add an entry to versions.json.
  2. npm run release.
  3. git tag <version> (no v prefix) and push.
  4. Publish a release with manifest.json, main.js, styles.css and the zip attached.

Pushing the tag makes .github/workflows/release.yml build and publish the release automatically.

License

GPL-3.0-or-later — see LICENSE.

Copyright (C) 2026 Zonvon