A table of contents for your SQL and HTTP files

How it works

1. 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.

2. Open Comment Outline

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

3. 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.

• Six heading levels for SQL, HTTP and REST

  .sql, .http and .rest files. Markdown # through ###### become a tree. A skipped level attaches to the nearest shallower heading, and same-level headings keep file order.

• Click or Enter to jump, type to search

  Click a heading, or move with the up and down keys and press Enter, to jump to the comment line. Type in the tree to search headings — no dialog to open first.

• Follows the editor, refreshes without saving

  The panel follows whichever editor is selected and rebuilds the outline about 250 ms after an edit. The file does not have to be saved.

• Expand, collapse, keep your place

  Expand or collapse any node, plus expand-all and collapse-all. Folding state is kept while you edit the same file, and resets to expanded when you switch files.

• HTTP ### separators, with a plain-comment fallback

  ### Request name separators from the HTTP Client become level-2 nodes, and empty ### lines are skipped. A file with no headings and no request names at all falls back to a flat list of its ordinary comments.

• The Java and Kotlin popup is still there

  The existing comment navigation popup for Java and Kotlin is retained and opens from the same Comment Structure action (Shift+Cmd+F12).

• Works in Scratch files as well as project files — ever-growing scratch scripts are the reason this plugin exists.
• No dependency on the SQL/Database or HTTP Client language plugins: parsing uses the platform Document API.

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.

-- # 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';

// # Freezer queries
// ## Normal cases
# ### Response field check

### List freezers
GET {{host}}/freezers

// # Replenishment
### Replenishment detail
GET {{host}}/replenishments/example

Rules that apply to both

• 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.
• Ordinary comments do not pollute an outline that already has explicit headings.
• A file with no headings and no request names at all falls back to a flat list of ordinary comments.

Install

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

1. Marketplace listing is being set up

   The JetBrains Marketplace listing for this plugin is not live yet, and there are no GitHub Releases either. Until it is published, build the installable ZIP yourself — the steps below take one command.

2. Build from source

   Clone the repository and run ./gradlew test buildPlugin with JDK 25. The installable package is written to build/distributions/comment-navigation-1.1.0.zip.

3. 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.

4. 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.

This version is built for and verified on IntelliJ IDEA 2026.2 (build 262.*). Earlier IDE versions are not in the compatibility range. Building from source needs JDK 25.

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

Frequently asked questions