Table of Contents from Headers

, ,
#1

I know there’s a toc widget that displays sub-tiddlers, but what I’m looking for is a table of contents that links to headings within the same tiddler. Is there a widget/macro/plugin, etc. that will do this?

#2

by headings are you referring to those defined using ! !! !!! etc? if so there are ways. they are html <hn> tags.

it’s easier if you are happy to do it manually, a little harder automatically. one reason for this is heading tags are common in tiddlywiki and we can open more than one tiddler and see another set of headings. we need to make headings unique if we want to provide a link to that specific heading. it’s common to do this in html using anchors, but html is often a series of pages at a time, where in some ways tiddlywiki is many pages/tiddlers at a time .

1 Like
#3

Do ask if you need more help.

1 Like
#4

Give this a try: TiddlyTools/InfoTOC. It uses the HTML “anchor” links for intra-tiddler navigation, where <a href="##..."> syntax creates clickable links that can autoscroll to <a id="#..."> “anchor” points embedded within the body of a tiddler.

Note that this does NOT automatically find HTML heading elements (H1 through H5), which can be created in TiddlyWiki using the ! through !!!!! wikitext syntax.

Instead, it uses some TiddlyTools custom macros that you can /import into your tiddler to generate and display an <<infoTOC>> table-of-contents containing <a href="##...">...</a> links at the top of a tiddler, and then you manually insert the corresponding named <<id "...">> (or <<idlink "...">>) macros to indicate your desired “anchor points” within your tiddler content. Clicking on a link in the table-of-contents can then autoscroll to its matching anchor point.

The <<infoTOC>> also permits you to manually specify multiple levels of indentation for the table-of-contents display items, and also provides a convenient <<top>> macro that you can embed in multiple places anywhere in your content for a quick “return to the top” autoscroll of the tiddler.

In addition to the macro definitions, the TiddlyTools/InfoTOC tiddler contains some basic instructions on how to set things up, and you can see the results in action by visiting some of my TiddlyTools add-on documentation tiddlers, such as TiddlyTools/Time/Info and TiddlyTools/Macros/edit-list/Info.

Let me know if you have any questions or need help getting things set up…

enjoy,
-e

3 Likes
#5

I’ve just uploaded a MAJOR improvement to TiddlyTools/InfoTOC that make setup and maintainence considerably easier…

  • You no longer need to define a separate infoTOC-items() macro to specify the list of items to be shown in the <<infoTOC>> table-of-contents. Instead, you simply embed the <<id "some text">> and/or <<idlink "SomeTiddlerTitle">> items within your content, and the <<infoTOC>> macro automatically extracts the list of items by scanning the text of your tiddler!

In addition to reducing the size of your tiddlers, this new method also avoids any potential problems that could be caused by mismatches between the items listed in the old infoTOC-items() definitions and the embedded <<id ...> macros.

Also note that in order to avoid any potential parsing conflict between indented InfoTOC items and the >> used to indicate the closing delimiter of a TiddlyWiki macro, I’ve changed the indentation symbol from > to +. Thus, you will need to use + to indent items in the table-of-contents display. Just include the + prefix as part of the <<id>> macro’s parameter value (e.g. <<id "+this is indented">>). The prefixes will be used in the table-of-contents, but will be suppressed in the output of the embedded <<id>> macros.

Another improvement is that, if you were to import your content tiddler into another TiddlyWiki, but NOT import the TiddlyTools/InfoTOC into that TiddlyWiki, your content tiddler will “degrade gracefully” and simply omit the table-of-contents from the display of your content tiddler, while still correctly handling any embedded <<goto>>, <<id>>, and <<idlink>> macros.

If you choose to update, please carefully read the new instructions at TiddlyTools/InfoTOC and make the appropriate changes to your tiddler content.

Let me know if you have any issues…

enjoy,
-e

#6

Just curious, what would it take to indeed make that work for a ToC? I.e some mechanism that would enable the user to merely call a macro at the top of a tiddlers text, and have it generate a ToC consisting of links to the various ! and !! etc in the tiddlers succeeding text? Spontaneously I’m guessing the trickiest bit would be to somehow make ! and !! become anchors, right?

(Maybe some other markup could be introduced, say !# and !!# etc, so !# Foobar is parsed into <a id=<<qualify "#Foobar">>><h1>Foobar</h1></a> ?)

#7

generate a ToC consisting of links to the various ! and !! etc in the tiddlers succeeding text?

This part can be tricky to parse, but it would be similar to what the <<infoTOC>> macro is currently doing to find all the embedded <<id ...>> and <<idlink ...>> macro syntax, extract the ID values, and generate the infoTOC output.

Spontaneously I’m guessing the trickiest bit would be to somehow make ! and !! become anchors, right?

Yes. This is VERY difficult to do without either:

  • Permanently modifying the underlying tiddler source text to insert anchor points. In addition to being hard to do, it would result in a real change to the tiddler content that the user may not want.
    or…
  • Use some javascript code to process the DOM output of the rendered tiddler content to locate all the rendered H1 through H5 elements and then generate and insert anchor elements into the DOM.

Also, even if one of these techniques could be reliably implemented, it would result in infoTOC entries for every header in the tiddler content… which is probably not what is needed for most use-cases, where I expect that the user would only want certain important headings to result in infoTOC entries.

(Maybe some other markup could be introduced, say !# and !!# etc, so !# Foobar is parsed into <a id=<<qualify "#Foobar">>><h1>Foobar</h1></a> ?)

This would require some custom javascript code to add a wikitext parser for the new syntax and, in any case, is similar to what the user already does when they manually decide to embed <<id ...>> and <<idlink ...>> macros to add specific anchor points in their text content (which, by the way, don’t have to be in a heading… any desired text can be made into an anchor).

With my solution, no javascript code is needed and, if the TiddlyTools/InfoTOC tiddler is missing – e.g., import a content tiddler into another TiddlyWiki, but don’t also import the TiddlyTools/InfoTOC macro – then, as long as the <<goto>>, <<id>> and <<idlink>> macros are present in the content tiddler, it can “degrade gracefully” and still produce perfectly suitable output (just without the InfoTOC display).

-e

#8

Please note:

In order to avoid any possible confusion the TWCore’s recursive “table-of-contents” macros (as well as 3rd-party TOC solutions such as @pmario’s tocP and my own TiddlyTools/TOC):

I’ve renamed TiddlyTools/InfoTOC to TiddlyTools/InfoNav. This includes changing the macro from <<infoTOC>> to <<infoNav>>.

-e

#9

I have not yet experimented with @EricShulman’s solution in this topic, but had some ideas of my own, I have a Proof of concept that I am developing further. I will share when I have it, and will review Erics approach to see what the pros and cons are of each approach.

  • I have an alternative way to represent the various headings ! !! !!! !!!! !!!!! which means they have an id=“heading title” (perhaps I will qualify) and using this method its easy to build an “inner toc macro”
  • I have also made an anchor symbol optionaly appear on such headings, and aim to allow click to copy to the clipboard a link to that heading to use outside the inner toc.

Just to forshadow how I am doing this one will need to enter not !!!My heading but {{My Heading||!!!}} which displays the same but gains an ID. I could create an editor toolbar button to generate this from from the standard form !!!My heading and back.

I think we may be able to alter $:/core/modules/parsers/wikiparser/rules/heading.js to not just wrap the content in Hn tags but also set a qualified ID. This set an anchor. It would be nice if this worked out of the box. Note that as a rule all headings by definition are the only thing on the current line and have 1-6 ! which could be replaced with 1-6 : or * in the toc