A Sublime Text 2 & 3 plugin that lets you organise and quick-jump between headings in your comments (like "jump to symbol") as well as optionally output a live table of contents within your document.
Organise your code with headings within your comments then run the plugin to open the quick-jump panel and easily navigate between sections of your document. Not only does it help you navigate your code quickly with custom headings, it keeps you organised and mindful of the overall structure of your document.
Open your command palette -> Package Control: Install Package -> Table of comments
Go to your packages folder(Preferences -> Browse Packages)
# clone this repo
git clone https://github.com/kizza/Table-of-comments 'Table of comments'Or download the leatest release
and unzip it in a folder named Table of comments
Simply start using headings within comments to organise your code using the format below. By default titles are represented by ">" but each title prefix can be customised via the settings.
/*
* > Heading 1
*/
...
/*
* >> Heading 2
*/
...
/*
* >>> Heading 3
*/
The easiest way to run the plugin is via a keybinding so that you can open the quick-jump menu quickly whilst typing.
-
Add a keystroke binding within your preferences (recommended) Open "Preferenes -> Key Bindings - User" from the main menu then paste
{ "keys": ["f1"], "command": "table_of_comments" }(This example runs the plugin by pressing F1)
-
You can also run the plugin via the command palette (Crtl+ Shift + P). Simply find and execute "Table of Comments: Show"
Then just like how you are able to quick-jump between functions and selectors you can now jump between the documentation and comment headings within your document.
You can also move to the next/prev comment from your local position. Here are some examples of the keybindings you can set in "Preferenes -> Key Bindings - User" from the main menu.
{ "keys": ["alt+up"], "command": "table_of_comments", "args":{ "move":"up" } }
{ "keys": ["alt+down"], "command": "table_of_comments", "args":{ "move":"down" } }
Feel free to set any keyboard shortcuts you like. (This behaviour inspired by by Sublime Move By Symbols plugin)
Current comment section (or all sections) can be folded and unfolded using commands or keyboard shortcuts. Here are some examples of the keybindings you can set in "Preferenes -> Key Bindings - User" from the main menu.
Fold and unfold current section
{ "keys": ["alt+["], "command": "table_of_comments", "args":{ "fold":true } }
{ "keys": ["alt+]"], "command": "table_of_comments", "args":{ "unfold":"true" } }
Fold and unfold all sections
{ "keys": ["alt+shift+["], "command": "table_of_comments", "args":{ "fold":"all" } }
{ "keys": ["alt+shift+]"], "command": "table_of_comments", "args":{ "unfold":""all"" } }
You can optionally output a maintained list of the headings within your document by placing "TOC" inside a separate comment anywhere within the document.
For example placing...
/* TOC */
...anywhere in your document will automatically update it to reflect the headings within your comments each time you run the plugin.
/*
* TOC
*
* Heading 1
* - Heading 2
* -- Heading 3
* --- Heading 4
*/
You can change the title for your table of contents within the plugin settings.
For example, you can change "TOC" to be "Within this document", then simply place
that text within a comment in your document to have the table of content maintained
with that heading.
You can tweak the plugin settings for parsing headings (ie. which characters designate each level of headings) as well as for formatting the table of contents output.
To view the existing plugin settings run the command "Table of comments: Settings - Default" from the command palette (Ctrl + Shift + P). Then run "Table of comments: Settings - User" and paste in any of the settings you wish to change.
Ultimately the above creates a "tableofcomments.sublime-settings" file in your "Packages/User" directory.
For example you can use colons to designate level headings...
/*
* : Heading 1
*
* :: Heading 2
*
* ::: Heading 3
*/
By using the setting...
"level_char": ":",
Rather than "TOC" designating the comment to be updated with your table of contents you could enter the setting...
"toc_title":"Within this document"
Which means you can use the comment below to manage your table of contents
/* Within this document */
If you've dilegently organised lots of first, second and third headings within your document for the purposes of quick-jumping around, it may be too much to display them all within the table of comments.
You could of course not include the /* TOC */ comment in your document, or use the setting below to only show first level headings.
"toc_level":"1"
To generate the TOC you need to enable the following configuration:
"toc_generate_on_save": true