create new tag
, view all tags

Feature Proposal: Allow an Include or a Search to increase/decrease header levels of extracted text


One of TWiki's strengths is the ability to reuse information from other pages using the %INCLUDE and %SEARCH% variables.

However the headers in the included text often don't fit into the new header hierarchy in the including page. This isn't surprising since the headers of the included page form their own hierarchy that doesn't need to match that of the including page.

For example: I include a section of the page IncludeMe that has headers at level 2 and 3 (---++ and ---+++). I want to include the text under a header at level 3. Currently I will end up with level 3 header from the including document, followed by a level 2 header and a level 3 header from the included document.

What I need is a level 3 header from the including document and the level 2 header from the included document moves to a level 4 header. Then the level 3 header from the included document moves to level 5 to maintain the relative header relations of the included document within the including document.

Description and Documentation

I suggest adding a new parameter headershift to %SEARCH% and %INCLUDE%. It will take a single integer argument in the range -6 to +6. It will accept a value of 0, which produces the same output as when the parameter is not seecified.

It will take any headers in the included/search extracted text and shift them by the specified amount. Positive numbers shift away from an H1 header toward an H6 header. Negative numbers move in the opposite direction.


The twiki variable:

 %INCLUDE%{"!ThisTopic" headershift="2"}%

will take any header at level 2 in the included part of ThisTopic and shift it to level 4. A level 3 header becomes a level 5 header and a level 4 or greater header becomes a level 6 header (since there is no H7 tag in html).


 %SEARCH%{"!ThisTopic" headershift="-1" format="%pattern(...)"}%

Will move an H6 tagged item to header level 5 (H5). Any level 1 or 2 header item in the extracted part of ThisTopic becomes a level 1 header in the displayed document.



WhatDoesItAffect: Documentation, Rendering, Search, Usability, Vars


-- Contributors: JohnRouillard - 09 Apr 2008


I agree - I would also like to see a headershift="relative" which would rejig the header levels to put the INCLUDED headers automatically to the correct level for the topic its being brought into - though this will need to have some sort of delayed processing, where all the other TML processing is done, then the heading levels are resolved.

Additionally, it would be useful to be able to set a min and max header limit for a web / twiki - I'd like my topics to never define a h1, irrespective of the user's input, as the h1 is set via a topic name / heading, which is then the same as the title...

-- SvenDowideit - 09 Apr 2008

This is done for INCLUDE in IstanbulRelease in RelativeHeadingLevelsforINCLUDE. Feature pending for SEARCH.

I suggest to create a new feature proposal for adjusting header level of SEARCH.

-- PeterThoeny - 2010-07-29

Let's close this proposal. Follow-up for SEARCH enhancement in RelativeHeadingLevelsforSEARCH.

-- PeterThoeny - 2010-07-29

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2010-07-29 - PeterThoeny
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.