Free & open sourceMIT LicenseIntelliJ IDEA 2025.1–2026.2

A table of contents for your SQL and HTTP files

Name: Code Comment Navigator
Availability: InStock
Author: Fuuqiu

Write Markdown headings in your comments — -- # Heading in SQL, // # Heading in HTTP — and IntelliJ IDEA shows them as a collapsible Comment Outline you can click to jump. It works in project files and in Scratches, where iteration scripts grow longest.

Install from JetBrains Marketplace Copy AI Skill

Version 1.2.4 · MIT License · runs locally, no network code · IntelliJ IDEA 2025.1–2026.2

Scratches and Consoles

orders.sql

-- # Order analytics
-- Paid orders only, grouped by order date.

-- ## Daily totals
SELECT DATE(o.created_at) AS order_date,
       COUNT(*)           AS order_count,
       SUM(o.amount)      AS total_amount
FROM orders o
WHERE o.status = 'PAID'
GROUP BY DATE(o.created_at)
ORDER BY order_date DESC;

-- ## Per customer
/*
 * ### Repeat buyers
 */
SELECT o.user_id, COUNT(*) AS order_count
FROM orders o
GROUP BY o.user_id
HAVING COUNT(*) > 1;

-- # Customer profile
-- ## Active users

Comment Outline

orders.sql

Order analytics
Daily totals
Per customer
Repeat buyers
Customer profile
Active users

Scratches

Scratches and Consoles › orders.sql 4:1 LFUTF-8SQL

One command, and your AI writes files with a navigable outline

Install this Skill in the AI tool you already use, and the SQL and HTTP files it writes come organised under short comment headings you can click through in Comment Outline.

Claude Code

mkdir -p ~/.claude/skills/comment-navigator && curl -fsSL https://commentnavigation.plugins.topxup.com/skills/en/comment-navigator/SKILL.md -o ~/.claude/skills/comment-navigator/SKILL.md

Run it in a terminal. SKILL.md is saved to your personal Claude Code skills folder.

Codex

mkdir -p ~/.codex/skills/comment-navigator && curl -fsSL https://commentnavigation.plugins.topxup.com/skills/en/comment-navigator/SKILL.md -o ~/.codex/skills/comment-navigator/SKILL.md

Run it in a terminal. SKILL.md is saved to the Codex skills folder.

Cursor

mkdir -p .cursor/rules && curl -fsSL https://commentnavigation.plugins.topxup.com/skills/en/comment-navigator/SKILL.md -o .cursor/rules/comment-navigator.mdc

Run it in your project root. The file is saved as a Cursor project rule.

Paste anywhere

Download SKILL.md

Paste it at the start of the conversation, then describe your task.

What AI writes by default → with the Skill

AI by defaultBanner lines, hand-numbered sections, prose that repeats the code

-- ============================
-- 1. Query orders
-- ============================
-- This query reads data from the orders table,
-- counts orders and sums the amount per day,
-- and only includes orders that are paid.
SELECT DATE(created_at) AS day, COUNT(*), SUM(amount)
FROM orders
WHERE status = 'PAID'
GROUP BY DATE(created_at);

With the SkillTwo headings, which become two levels in Comment Outline

-- # Order analytics
-- ## Daily totals of paid orders
SELECT DATE(created_at) AS day,
       COUNT(*)    AS order_count,
       SUM(amount) AS total_amount
FROM orders
WHERE status = 'PAID'
GROUP BY DATE(created_at);

Read the full Skill

---
name: comment-navigator
description: Generate or organize SQL and JetBrains HTTP Client .http/.rest files with Markdown headings inside comments for Code Comment Navigator. Use when the user requests an outline-ready SQL script, API request file, or Scratch file. This skill does not execute SQL or send requests.
---

# Code Comment Navigator file conventions

Preserve the requested SQL dialect, API contract, variables, business logic, and content language. When reorganizing a file, preserve query semantics, request order, and pre/post-request scripts. Verify missing schema or API details; use explicit placeholders in examples and never invent real credentials.

## Outline structure

- Use 1–6 hashes for heading levels, followed by a space and a non-empty title.
- Use business domain, operation/query, and scenario groups only as needed. Prefer consecutive levels and short, distinguishable titles. Siblings keep file order.
- Add headings to meaningful sections, not every explanatory line. Use ordinary comments for ordinary notes.
- With explicit headings, ordinary comments stay out of the outline. Without headings, the plugin falls back to a flat comment list. Skipped levels attach to the preceding shallower heading.

## Keep files concise

- Replace decoration with headings. Do not generate `====`, `----`, asterisk borders, ASCII banners, or a hand-written table of contents. Preserve HTTP `###` request separators.
- Give each independently useful query or request scenario one short heading. Add shared groups only where useful; 1–3 levels usually suffice. Do not stack synonymous domain/operation/scenario headings or annotate every statement, field, or step.
- Titles name the query, operation, or scenario. Keep lengthy explanations, line numbers, and section numbering out of headings. At the top, include only necessary purpose and prerequisites, not the full requirements, API documentation, change history, or business specification.
- Ordinary comments explain what code cannot: business definitions, units, time zones, dependencies, significant side effects, or expected results. Prefer 1–2 nearby lines. Do not narrate obvious code; use clear parameter names and column aliases.
- Put detailed procedures, formula derivations, and verification reports in the conversation or existing user documentation. Create companion documentation only when needed by the user. Preserve constraints, transaction/request dependencies, and warnings needed for correct use.
- When organizing old files, replace numbered chapter banners with explicit headings and remove repetitive prose. Retain at least one meaningful explicit heading so ordinary comments do not all become fallback outline entries. Preserve execution order, parameters, and semantics.

## SQL

Prefer standalone `-- # Heading`, `-- ## Heading`, and `-- ### Heading` lines. Headings inside `/* ... */` comments also work, including lines prefixed with `*`. Do not put headings after a SQL statement on the same line. MySQL `#` line comments are also supported: `# Plain note` appears in the fallback outline when no explicit headings exist. Use `# # Level one` and `# ## Level two` for headings: the first hash is the comment marker, and the remaining hashes define the Markdown level. When explicit headings exist, ordinary notes stay out of the outline. Hashes inside strings are not headings. Prefer `--` for other SQL dialects; do not change dialect syntax just to standardize formatting.

```sql
-- # Order analytics
-- ## Daily paid orders
SELECT CAST(paid_at AS DATE) AS paid_date,
       COUNT(*) AS order_count,
       SUM(total_amount) AS paid_amount
FROM orders
WHERE status = 'PAID'
GROUP BY CAST(paid_at AS DATE)
ORDER BY paid_date;

-- ## Missing payment timestamps
SELECT id FROM orders WHERE status = 'PAID' AND paid_at IS NULL;
```

For long scripts, use relevant sections such as schema, indexes, seed data, migrations, and analytical queries. Do not add unrelated SQL to inflate length. Preserve transaction boundaries and dependency order.

## JetBrains HTTP Client (.http / .rest)

Prefer an empty `###` request separator, followed by `// # Heading` through `// ###### Heading`, then the request line. The `# # Heading` form is also supported.

**After a JSON or other request body, place the next section's headings AFTER the next `###` separator.** Never place the next request's comments between the previous body and its following separator: the IDE can interpret them as part of that body. Separate headers from the body with a blank line. JSON must contain no comments or trailing commas.

```http
@host = https://example.invalid

###
// # Orders API
// ## Create order
POST {{host}}/orders
Content-Type: application/json

{
  "skuId": 1001,
  "quantity": 2
}

###
// ## Find order by ID
GET {{host}}/orders/example-order-id
Accept: application/json
```

This example demonstrates formatting; the host and resource ID are placeholders. Use existing project environment variables, authentication, and API contracts for actual output.

- `### Request name` is a native request separator and always produces a level-2 outline node, not a level-3 Markdown heading. For precise nesting, use an empty `###` plus `// ### Heading`; mixing the forms can change parent relationships.
- An empty `###` does not create an outline node. Do not change request boundaries just to create outline entries.
- Comments inside `< {% ... %}` pre-request and `> {% ... %}` response-handler scripts are excluded from the outline. Keep scripts attached to their requests and put the next section's headings after the next separator.
- Use existing variables or placeholders for authentication; never embed tokens or passwords in examples.

## Before delivery

1. Check that SQL headings occupy standalone comment lines and HTTP headings follow the corresponding separator. Each heading needs a space and a title.
2. Check every HTTP request boundary, especially after bodies. Validate JSON and preserve script-to-request associations.
3. Remove decorative banners, duplicate tables of contents, obvious narration, and synonymous heading stacks. Preserve necessary business definitions and warnings.
4. Check the intended business hierarchy, SQL dialect, statement semantics, transactions, and API contracts.
5. Return the complete requested files or requested edits. Do not claim SQL or requests were executed unless they were; this skill itself does not authorize execution.

Open the files with the plugin, inspect the right-hand **Comment Outline**, and click headings to verify navigation. If the environment cannot operate the IDE, say this check remains unperformed.

References: [Plugin source and examples](https://github.com/fuuqiu/CommentNavigation) · [JetBrains HTTP syntax](https://www.jetbrains.com/help/idea/exploring-http-syntax.html)

---
name: comment-navigator
description: 当用户要求生成或整理适配 Code Comment Navigator 的 SQL、JetBrains HTTP Client .http/.rest 文件时，使用注释中的 Markdown 标题组织可导航的大纲。适用于长 SQL 脚本、接口调试文件和 Scratches；不用于执行 SQL 或发送请求。
---

# Code Comment Navigator 文件规范

生成或整理文件时，保留用户要求的 SQL 方言、接口协议、变量和业务逻辑，采用用户指定的内容语言。只调整组织方式时，不改变查询语义、请求顺序或前后置脚本。缺少表结构或接口定义时先核实；示例使用明确的占位值，不编造真实凭据。

## 大纲组织

- 用 1–6 个 `#` 表示层级，标记后必须有空格和非空标题。
- 按需要选择业务域、操作/查询或场景分组，优先连续层级，标题简短且可区分。同级按文件顺序展示。
- 只给有意义的章节加标题，不把每行说明变成大纲节点。普通说明使用普通注释。
- 有显式标题时，普通注释不进入大纲；没有标题时才回退到普通注释列表。跳级标题会挂在前一个更浅的标题下。

## 保持文件简洁

- 用标题替代装饰：不生成 `====`、`----`、星号边框、ASCII 横幅或手写目录；HTTP 的 `###` 请求分隔符必须保留。
- 每个可独立定位的查询或请求场景只写一个简短标题；按需要增加共享分组，通常 1–3 级足够。不要为了凑齐“业务域 → 操作 → 场景”连续写同义标题，也不要为每条 SQL、每个字段或每行操作加注释。
- 标题写“查什么 / 做什么 / 哪种场景”，不在标题中堆放长解释、行号或章节编号。文件开头最多保留必要的用途与执行前提，不复制整份需求、接口文档、变更历史或完整业务说明。
- 普通注释只解释代码看不出的业务口径、单位、时区、前置依赖、重要副作用或预期结果，尽量就近用 1–2 行说明。代码已表达的步骤不再复述，参数名和列别名优先做到自解释。
- 详细使用步骤、公式推导、验证报告等放在对话回复或用户已有文档中；只有用户需要时再创建配套文档。精简时保留影响正确使用的约束、事务/请求依赖与风险提示。
- 整理旧文件时，将原来的编号章节或分隔线替换成显式标题，删除重复叙述；至少保留一个真实的显式标题，避免无标题时全部普通注释回退为大纲。保留执行顺序、参数和业务语义。

## SQL

优先使用独立行的 `-- # 标题`、`-- ## 标题`、`-- ### 标题`。也支持 `/* ... */` 内的标题（允许行首 `*`），但不要把标题放在 SQL 语句末尾。MySQL 方言也支持 `#` 行注释：`# 普通说明` 在无显式标题时参与普通注释大纲；层级标题写成 `# # 一级标题`、`# ## 二级标题`，第一个 `#` 是注释符，后面才是 Markdown 层级。有显式标题时仍只展示标题。字符串中的 `#` 不作为标题；其他 SQL 方言优先沿用 `--`，不为统一格式更换方言语法。

```sql
-- # 订单分析
-- ## 按日汇总已支付订单
SELECT CAST(paid_at AS DATE) AS paid_date,
       COUNT(*) AS order_count,
       SUM(total_amount) AS paid_amount
FROM orders
WHERE status = 'PAID'
GROUP BY CAST(paid_at AS DATE)
ORDER BY paid_date;

-- ## 缺失支付时间的订单
SELECT id FROM orders WHERE status = 'PAID' AND paid_at IS NULL;
```

长脚本可按建表、索引、种子数据、迁移、分析查询组织，按实际任务取舍，不为凑长度添加无关 SQL。保持原有事务边界和依赖顺序。

## JetBrains HTTP Client（.http / .rest）

优先采用独立的空 `###` 请求分隔符，再写 `// # 标题` 到 `// ###### 标题`，最后写请求行。`# # 标题` 形式也支持。

**前一个请求有 JSON 或其他请求体时，下一组标题必须放在下一个 `###` 分隔符之后。** 不要把下一请求的注释放在请求体与分隔符之间，否则 IDE 可能把注释当成请求体。请求头和请求体之间留空行，JSON 内不写注释或尾随逗号。

```http
@host = https://example.invalid

###
// # 订单接口
// ## 创建订单
POST {{host}}/orders
Content-Type: application/json

{
  "skuId": 1001,
  "quantity": 2
}

###
// ## 按编号查询订单
GET {{host}}/orders/example-order-id
Accept: application/json
```

上例仅演示格式，域名与资源编号是占位值。实际输出使用项目现有环境变量、鉴权方式和接口契约。

- `### 请求名称` 是原生请求分隔符，插件固定将它视为二级节点，并不是三级 Markdown 标题。需要精确层级时用空 `###` 配合 `// ### 标题`，避免混用导致父子关系变化。
- 空 `###` 不产生大纲节点。不要为了增加节点而改变请求边界。
- `< {% ... %}` 前置脚本和 `> {% ... %}` 响应处理脚本内的注释不进入大纲。保留脚本与其所属请求的关联，将下一组标题放在下一分隔符后。
- 鉴权信息使用项目已有变量或占位符，不把令牌、密码写进示例。

## 交付前自检

1. SQL 标题在独立注释行，HTTP 标题在对应请求分隔符之后；各级标题包含空格和正文。
2. 每个 HTTP 请求边界明确，尤其检查所有带请求体的请求；JSON 有效，脚本没有被移到其他请求。
3. 无装饰分隔线、重复目录、逐句解说和同义标题堆叠；必要业务口径与风险仍保留。
4. 大纲按预期呈现业务层级；SQL 方言、语句语义、事务与请求契约保持正确。
5. 输出用户所需的完整文件或指定修改。若未实际执行，不声称已执行 SQL 或请求；本规范本身不授权执行。

使用插件打开文件后，在右侧 **Comment Outline** 检查层级，点击标题跳转。若当前环境不能操作 IDE，明确说明这项检查尚未完成。

参考：[插件源码与示例](https://github.com/fuuqiu/CommentNavigation) · [JetBrains HTTP 语法](https://www.jetbrains.com/help/idea/exploring-http-syntax.html)

The commands, the copy button and the download all use the same file. No registration.

How it works

Write headings in comments

Mark sections with # to ###### inside an ordinary comment line — -- # Heading in SQL, // # Heading in HTTP. A space after the hashes is required. Nothing else about the file changes.
Open Comment Outline

Click the Comment Outline tab on the right edge, or go to View → Tool Windows → Comment Outline. The Comment Structure action in the editor context menu and the Edit menu opens it too (Shift+Cmd+F12 in the default keymap).
Click to jump, type to search

Click a heading — or select it with the up and down keys and press Enter — to jump to that comment line. Typing in the tree searches headings directly.

Iteration scripts in Scratches keep growing: a few hundred lines of SQL with no structure and no quick way back to the section you were reading. The outline gives that file a table of contents without changing how you write it.

Features

Everything the outline does, and nothing it does not.

Follows the editor, updates in about 250 ms

The panel follows whichever editor is selected and rebuilds the outline about 250 ms after an edit — no save needed. Empty or unsupported files clear it.
Search the outline

Click the gray file name at the top to turn it into a search box. Matches filter instantly, ignore case and keep their parent path; Up and Down pick, Enter jumps, Esc clears.
Scratches tree and file search

Click the Scratches bar at the bottom of the panel to open a tree of your scratch .sql and .http files with a file-name search box. Both areas scroll on their own; drag the divider to resize.
Create, drag and rename Scratch files

Press ＋ to create orders.sql, api.http or a folder inside the panel; new files open with a heading template. Drag a file onto a folder to move it — name clashes are reported, never overwritten. Right-click for IDEA’s rename, cut, copy, paste and delete.
Remembers what you folded

Expand or collapse any node, or everything at once. Folding state is kept while you edit the same file, and resets to expanded when you switch files.
Follows your IDE, stays local

The UI follows IDEA’s display language (Chinese or English, otherwise English) and its light or dark theme. The outline is built inside the IDE: no document content is uploaded, no telemetry, no ads.

No dependency on the SQL/Database or HTTP Client language plugins: parsing uses the platform Document API.
The existing comment popup for Java and Kotlin is retained and opens from the same Comment Structure action (Shift+Cmd+F12).

Heading syntax

Headings are ordinary comments. The database console and the HTTP Client still see plain comments, so a file stays runnable exactly as before.

SQL

-- # Roles and permissions audit
-- ## Role entities
-- ### System templates
SELECT 'system role';

-- ### Merchant roles
SELECT 'merchant role';

-- ## Grant details
/*
 * ### Page permissions
 * #### PRO pages
 */
SELECT 'page permission';

Comment Outline

Roles and permissions audit
Role entities
System templates
Merchant roles
Grant details
Page permissions
PRO pages

-- line comments, MySQL # line comments and /* … */ block comments are all read.
Each heading has to sit on its own comment line.
Trailing comments after a statement, strings and quoted identifiers are never mistaken for headings.

HTTP

@host = https://example.invalid

###
// # Orders API
// ## Create order
// ### Normal case
POST {{host}}/orders
Content-Type: application/json

{ "skuId": 1001, "quantity": 2 }

###
// ## Query orders
// ### Find by ID
GET {{host}}/orders/example-order-id

Comment Outline

Orders API
Create order
Normal case
Query orders
Find by ID

// # Heading is the recommended form; # # Heading — a hash comment plus a Markdown marker — works too.
### Request name is always a level-2 node, so do not use it for level 3; write // ### Heading when you need an explicit level.
Empty ### separators are skipped, and comments inside request pre/post scripts are ignored.

HTTP heading levels
Written as	Outline level
`// # Heading` or `# # Heading`	Level 1
`// ## Heading` or `# ## Heading`	Level 2
`// ### Heading` or `# ### Heading`	Level 3
`### Request name`	Level 2 — the HTTP Client request separator

Rules

A space is required after the hash marker. Levels 1 to 6.
A skipped level attaches to the nearest shallower heading; same-level headings keep file order.
Once a file has explicit headings, only headings are shown — ordinary comments and decorative separator lines stay out.
Without explicit headings, numbered sections such as 0. Parameters or 1. Endpoint notes are picked up first; only then does the outline fall back to a flat list of ordinary comments.
MySQL: write # # Role audit, # ## Permission details for levels. The first # is the SQL comment marker; the hashes after it set the level.
HTTP: after a request body, write the next ### separator first, then the next headings — otherwise they become part of the body.

Install

Two minutes, one command, and an IDE restart when IntelliJ IDEA asks for one.

JetBrains Marketplace

Live

Open the Marketplace listing and install the plugin into IntelliJ IDEA 2025.1–2026.2, or search for Code Comment Navigator in Settings → Plugins → Marketplace.

Install from JetBrains Marketplace

Install from source

Build

Clone the repository and run ./gradlew test buildPlugin with JDK 21. The installable package is written to build/distributions/comment-navigation-1.2.4.zip.
Install Plugin from Disk

In the IDE: Settings → Plugins → gear menu → Install Plugin from Disk…, choose the ZIP, and follow the IDE prompts to finish.
Open a SQL or HTTP file

Open a .sql, .http or .rest file, then click the Comment Outline tab on the right edge, or go to View → Tool Windows → Comment Outline.

Compatibility covers IntelliJ IDEA 2025.1–2026.2 (builds 251–262.*). The plugin builds against the 2025.1 SDK and targets Java 21 bytecode. Building from source needs JDK 21.

Want to see the outline before installing? The repository ships two example files: SQL example · HTTP example

Frequently asked questions

Is Code Comment Navigator free?

Yes. It is released under the MIT License and is free for personal and commercial use — no purchase, no subscription, no activation key. You may modify it, redistribute it and sell it as long as the copyright and license notices are kept. The software is provided as is, with no fixed update schedule and no promised support response time.

Which IntelliJ IDEA versions does it support?

Compatibility covers IntelliJ IDEA 2025.1–2026.2 (builds 251–262.*). The plugin builds against the 2025.1 SDK and targets Java 21 bytecode. Building the plugin from source needs JDK 21.

Do I need the Database or HTTP Client plugins?

No. Parsing uses the platform Document API, so the outline has no dependency on the SQL/Database or HTTP Client language plugins. It reads .sql, .http and .rest files on its own.

Does it send my code anywhere?

No. The plugin contains no network code. It only reads the text of the editor you have open and builds the outline locally inside the IDE.

Why does ### Request name show up as level 2?

Because it is the HTTP Client’s own request separator, and it is always mapped to a level-2 node so existing .http files keep working unchanged. Empty ### lines are skipped. When you need an explicit third level, write // ### Heading instead.

Does it work in Scratch files?

Yes. Project files and Scratches are both supported — the ever-growing iteration scripts people keep in Scratches are the reason the outline exists. Open the scratch SQL or HTTP file and the panel follows the editor as usual.

License and contact

You may modify it, redistribute it and sell it, as long as the copyright notice and the license notice are kept. The software is provided as is, without warranty. There is no fixed update schedule and no promised support response time.

Links

Questions, bugs and feature requests — open an issue, or write to fuuqiu@gmail.com.

A table of contents for your SQL and HTTP files

One command, and your AI writes files with a navigable outline

Claude Code

Codex

Cursor

Paste anywhere

What AI writes by default → with the Skill

How it works

Write headings in comments

Open Comment Outline

Click to jump, type to search

Features

Follows the editor, updates in about 250 ms

Search the outline

Scratches tree and file search

Create, drag and rename Scratch files

Remembers what you folded

Follows your IDE, stays local

Heading syntax

SQL

HTTP

Rules

Install

JetBrains Marketplace

Install from source

Build

Install Plugin from Disk

Open a SQL or HTTP file

Frequently asked questions

License and contact

Links