This discussion has been refactored from Ideas. It concerns linking within a wiki-page, e.g. for bookmarks and index/table-of-content type notation.


First, please read my introduction.

Ability to define bookmarks (or sections) within a page, and create a table of contents for them anywhere on the page. The table of contents displays as a bulleted list, and each bullet is a hyperlink to that section heading. In addition, the individual sections can be linked to from external pages.

In PikiePikie, this is done as follows:

  1. The table of contents is created by inserting: '=TableOfContents='.
  2. Section bookmarks are of the form '==<section title>==' increasing the number of consecutive '=' characters to create subsections. Thus, the top level text is wrapped in '==', the next level in '===', and so on.

Within the current page, inserting '#Section1', '#Section2', etc. ('[#Section1]' in JSPWiki) or a text link such as '[#Section1|Jump to Whatever]' creates a hyperlink to the section title.

Links to bookmarks on other pages could be accomplished using '[EditingTips#Section9]' to link to the relevant section on the page 'EditingTips'. This mechanism could also be used with an InterWiki link to a wiki that supports this feature.

In addition, each page should have an embedded bookmark for the top of the page so that inserting '#Top', or '[Top|#Top]' in JSPWiki, provides a jump to the head of the page.

In PikiePikie, the format of section titles may be defined in the site stylesheet. By default, the text is bold and the full length of the title line has a light blue background, which provides a good visual distinction between sections.

In JSPWiki, you can achieve a form of in-page linking using footnotes, but without the table of contents, and the originating link will be in superscript.

-- PaulDownes

Hm. The superscript issue is trivial to change with a simple modification of the CSS file. Though adding an automatic section reference (<A NAME="#headingname">) on each heading might be a good idea. This would allow you to make the table-of-contents thing quite easily, yes?

However, it should be noted that the table-of-contents technology is really used manage long pages, and writing very long pages is sort of against the wiki ideology. If you have a really long page, you should split it to multiple pages and just have a table-of-contents on a page of its own.

-- JanneJalkanen, 04-Dec-2002.

Well, I'd challenge that long pages are against wiki ideology. "Do what you will, but respect others" is what I consider the wiki ideology. The C2 wiki has some very long pages.

I keep a library of reference material and links in a wiki, and table of contents based on sections is a wonderful way to organize and make it easy to navigate to entries. And, it is extremely useful to link directly to section on a page from an external page.

I have experimented with adjusting the footnote font in the CSS file, but you can't avoid the formatting of the footnote heading which is enclosed in square brackets. Or can you?

If you add the section reference as you have suggested, one can manually create the table of contents - I'd settle for that. Please also add an automatic #Top reference.

-- PaulDownes, 12/05/2002

Hm. To continue this discussion: Automatical generation of section titles is quite difficult, since it is possible for people to move them around: A Section9 would no longer be Section9 after someone inserts a headline in the middle. Also, creating titles based on the heading itself means that if someone changes it later on, all references would be broken immediately.

So the wisest course might be to make "markers" ([#Section1]) that could then be automatically collected by a [TableOfContentsPlugin]?

-- JanneJalkanen, 22-Jan-2003

I don't like that marker idea very much. You have headings to structure a document and mark different sections, so why adding another layer of structure? To refer to such a section I would suggest to adopt the HTML-anchor idea. Whenever someone wants to refer to a particular section of a page he inserts [foo#fooRef] (or simply [#fooRef] to mark a certain position without a text) and can refer to it using [bar|fooPage#fooRef] from any page.

-- Torsten, 2003-01-24

Your markup is in line of what I was thinking, but references are not the problem. Marking where the references are, that's the problem. Do it automatically or manually?

-- JanneJalkanen, 24-Jan-2003

(Complete neophyte talking, this may be nonsensical.)

Why not generate an anchor whose name is the heading? If you re-ogranize the page but don't change the headings, links would still work. If you change the heading, external links break, but that's the nature of the web, anyway.

The suggested [TableOfContentsPlugin] would gather the links for all headings.

This would restrict in-page links to headings, but together with the footnotes there would be plenty of options.

-- PaulDownes, 01/24/2003

I'd vote for manually creating an anchor, if someone wants to link to a section. The links/anchors a TOC-plugin uses should be completely independent of that and would probably use some numbering scheme to create unique anchors. I don't think someone should rely on these to link to a section.

Adding manual anchors is not only as independent of changes to the page as possible but also has the benefit, that anyone editing/refactoring a page later can see that this particular section is referenced from somewhere else, so he might also have to find/change these other places to prevent broken links.

As a further step you could even make ReferenceManger aware of these anchors to provide something like UnreferencedPages/ReferencedBy on a sub-page level (e.g. as small boxes that appear if you move your mouse over an anchor (that has to have some visible contents in that case of course)).

-- Torsten 2003-01-24


Any further thoughts on implementing this feature?

I disagree (respectfully) with Torsten, I think an anchor should be automatically created for each section title, simplifying things for the user.

This is the one feature I think JSPWiki really lacks. Consider the uses: pages like JSPWikiFAQ, New Ideas and many others would benefit enormously from a "table of contents" or index at the top of the page that allows a user to both view the contents of the page and jump to the section wanted. At this time, you have to scroll the entire page to find a topic.

Regretfully, lack of this capability this is holding back my full-scale adoption of JSPWiki to replace PikiePikie. I have many FAQ-like pages, and it would really reduce usability for users.

Ah, heck. I really like JSPWiki, and I'm going to convert anyway. If I have to, I'll embed HTML to get the capability. It will make the content conversion complex, but it's do-able. However, if this capability is subsequently added I'll have to remove that HTML and I will be 08_frown.png.

-- PaulDownes, 02/25/2003 (who wishes he was competent enough to contribute to the code)


I think a TOC is really needed. Especially for FAQ-type pages, but also many others. The TableOfContents plugin (if that's what it gets called) should automatically collect the appropriate section information from the page in order to generate the contents (say, a bulleted list with nested lists for subsections, etc) as a convenience to the authors. However, I think there also needs to be a way to manually specify a tag/marker/label which can be used for internal and external linking, so that your links aren't dependent upon the actual text of the sub/section (although that could be used as a default value, too?).

I think the question is more of how it should be done instead of should it be done.

--MichaelGentry, 2/25/2003

I can see how I'd like TOC's, and I sort of agree that a longish page can be more elegant than a largish number of separate ones. But - asking as a newbie to this discussion - why not apply the KISS, and collect the TOC directly from the HTML header tags? In what cases would you want to have separate structure for the page and for the TOC?

I'd be happy enough with this:

[{TOC}]
!!Q: foobar?
!A 1: foobars in frobozz
...
!A 2: foobars in aqueducts
..

producing something like this:

<div class="TOC">
<h1><a href="#tocitem1">Q: foobar</a></h1>
<h2><a href="#tocitem2">A 1: foobars in frobozz</a></h2>
<h2><a href="#tocitem3">A 2: foobars in aqueducts</a></h2>
</div>
...
(continue with normal translated output, except with added anchors)

...and using CSS to render the TOC as you wish. Is this somehow too simplistic? It doesn't require the need to learn a new tag and to edit an old page to add a TOC. It forces the TOC to tie in closely with page structure, which I think is sort of the point of TOCs. (OK, you probably want to be able to leave lower level headers out, but that's just a plugin option.)

--ebu

This does not work too well if you want the ability to refer to sections across pages. For example, Referring from another page, [Aqueduct#tocitem1] would point to the wrong entry if someone changed the ordering of things. This is why some people think that the generated code should be something like this:

<div class="TOC">
<h1><a href="#Qfoobar">Q: foobar</a></h1>
<h2><a href="#A1foobarsinfrobozz">A 1: foobars in frobozz</a></h2>
<h2><a href="#A2foobarsinaqueducts">A 2: foobars in aqueducts</a></h2>
</div>

Unfortunately, in this case, if someone edits the header, all hyperlinks across pages break again.

(BTW, all page references must be of the form '#pagename_tocid', because otherwise it would be dangerous to include the contents of two WikiPages in the same JSP page.)

--JanneJalkanen

Is the breakage a problem, if the plugin generates the TOC on-the-fly each time a page is viewed? Hum, yes, caching. A page would have to declare itself non-cacheable, or ask to be notified when other pages change and invalidate its caching... OK, not necessarily trivial.

--ebu

Yes, of course, since any references from other pages would not work, or would work erroneusly.

--JanneJalkanen

Have you considered a tag that would generate the TOC link page as a separate page that would be associated with the content page? I'm not sure of the internal details of the JSPWiki cache, but everytime the Content page (the one that contained the TOC plugin), were modified, it could reconstruct the TOC and save it to the separate file as regular jspwiki markup. A content page could only have one TOC page associated with it, and when the Content were loaded it would include the TOC. The Combined TOC/Content page would be cached until a change to either Content or TOC forced the cached version to be replaced? Ok, perhaps it is slightly convoluted...

--RobSeegel

If you need to generate unique values for node ids (questions in a faq, header tags, whatever) why not just modify the algorithm described at http://www.jwz.org/doc/mid.html. It's been used to generate a lot of message id's in an email program. Granted you will need to reduce the size of the value by quite a bit to keep it manageable but that shouldn't be too difficult. Then team that algorithm with a plugin or filter that examines every structural node to see if it has an ID attribute already. If it does the filter does nothing. If the node lacks an ID attribute, one is generated and assigned. --matt


OK, this feature is now available for testing in 2.1.78. I've pasted the relevant portion of the documentation below (note that it does not work here yet =).

Each heading that you use generates also a "named anchor" into the HTML file. This allows you to refer to a section of a wiki page.

For example, if the heading on this page is called

!!This is my heading
The resulting HTML code would look like
<h3><a name="section-NamedHeadings-ThisIsMyHeading">This is my heading</a></h3>

This allows you to refer to the heading from a different wiki page. And you can use it from WikiMarkup as well! For example, saying TextFormattingRules#PreformattedText (which looks like this in WikiMarkup: [TextFormattingRules#PreformattedText] refers to the "Preformatted text" -section of the page TextFormattingRules.

If you are too lazy to figure out what the link name is, you can also just type the heading as-is: [Text formatting rules#Preformatted text].

Note that this does not work with CamelCase links.

Unfortunately, at least now there's no way to gather these references from TranslatorReader. If I figure out a good way to do it, we should be able to write a TableOfContentsPlugin.

A trick to do invisible references (i.e. free-form bookmarks) in 2.1 is to say:

%%(display:none)
!My reference here
%%

:-)

--JanneJalkanen, 10-Oct-2003

Are we making any headway on adding TOC into the V2? We could really use it.

-- DainHansen, 16-Dec-2003

Is there an easy way to refer to anchors in the same page, without having to spell the name title? I tried using the pagename WikiVariable but it does not work inside the brackets used to indicate a link. I just want something like the footnote notation without the superscript.

-- Nascif, 26-Jul-2004

GISWiki with JSPWiki is no longer online. I've deleted some lines.-- Heinz-Josef L├╝cking 13-OKT-2005


Category Ideas

Add new attachment

Only authorized users are allowed to upload new attachments.

List of attachments

Kind Attachment Name Size Version Date Modified Author Change note
png
08_frown.png 0.3 kB 1 25-Feb-2003 18:18 164.109.144.90
« This page (revision-33) was last changed on 10-Jun-2012 10:43 by Janne Jalkanen