create new tag
, view all tags

Relative Heading Levels for INCLUDE


Heading levels can be off when a big document is composed of many included topics. This can be fixed of there is a way to adjust the level of headings in INCLUDEd topics.


Add this in VarINCLUDE:

Parameter: Description: Default:
headingoffset="2" Adjust the level of headings in the included topic. A "2" or "+2" increases the level by two, e.g. a ---+ H1 turns into a ---+++ H3. Positive and negative values are supported. Adjusted min and max levels are H1 and H6, respectively. no adjustment


SomeTopic has this:

---+ Cars
---++ Sedans
---+++ BMW
---+++ Mercedes
---++ Trucks
---+++ Mack
---+++ Volvo

Now, if you %INCLUDE{ "SomeTopic" headingoffset="1" }% you get this result after the include:

---++ Cars
---+++ Sedans
---++++ BMW
---++++ Mercedes
---+++ Trucks
---++++ Mack
---++++ Volvo

E.g. it changes H1 to H3, H2 to H4, etc.

-- Contributors: PeterThoeny - 2010-06-22


I use %INCLUDE ... fairly regularly.

It always places me in a quandary: should I start my include headings as level H1, e.g. ---+, or should I arrange them to start at some deeper level, like H3, ---+++.

If I start at H1, then the included headings may mess up a table of contents in the includer.

If I start at a deeper level, then the page itself may look a little bit odd.

Enhancement request: add a parameter to INCLUDE to indicate what heading level ---+ should correspond to. E.g.

   ---++ H2

-- AndyGlew - 26 Oct 2004

Interesting idea. If we had ParameterizedIncludes you could do this:

   ---++ H2
   %INCLUDE{"PageBeginningAtH1" hbase="+++"}%
and then in the page
---%hbase% A heading

-- CrawfordCurrie - 26 Oct 2004

I asked the same question in Support.AdjustingHeadingsDuringInclude

-- MartinCleaver - 26 Oct 2004

It's not clear from above if this is intended so I'll say it.

The base should be reletive to the lowest non-hidden (from TOC) heading of the included topic. So if you include with a base of ---+++, it would skip a ---+!! heading, find the lowest (not necessarily first) non-hidden heading of ---++ and then increase all headings by 1.

-- SamHasler - 26 Oct 2004

Dynamically showing sections depending on their header level was not meant, I think. Wouldn't NamedIncludeSections and hand-crafted including topics already address that need?

AndyGlew addressed tho old problem, that topics have fixed header levels in them. If you want to re-use a topic in a bigger paper, the header levels can be right only for one view. So either your single page has odd tiny headings, or your big printed manual has a lousy table of contents, see TWikiForBookAuthoring or PrintUsingPDF.

The proposed syntax of INCLUDE{... hbase="+++"} looks good. Not sure I would want to edit all included topics to switch to
---%hbase% A Variable Heading. Why not simply let them as-is, implicitely adding the hbase on the go? So you write
---+ A Fixed Heading Level 1, but within an
INCLUDE{... hbase="2"} it would turn into <h3>. Recursive INCLUDES should add relative to the current shift level, then the end of the INCLUDE would restore the previous shift level. An absolute shift is easier to implement, but would introduce the same problem again, if you include including pages.
Hmm. A relative level is probably more appropriately named hshift

-- PeterKlausner - 29 Oct 2004

"Dynamically showing sections depending on their header level was not meant, I think."

It's not what I meant either. By skip I meant for the purposes of determining relative heading levels, all the included content would still be included. Now that I think about it, it's not a good idea. Headings that don't appear in the TOC are usually

The reason I think the base should be relative is so that you can change the depth of all the headings in the included topic to be one deeper/less deep without affecting their depth in the topic they are included into.

Base to Include at Headings in topic to include Headings how they will
appear once included
---++ ---+
---+++ ---+
---+++ ---++



-- SamHasler - 29 Oct 2004

It would be really good if someone took ownership of a project to address this question. I can offer an extended include, but it's obvious from the various plugins and TWikiForBookAuthoring that some greater smarts need to be applied to headings, web-wide, in includes, and the assembly of TOX.

-- CrawfordCurrie - 29 Oct 2004

A guest in Support.IncludingTopicButLoweringHeadingLevel suggest this syntax:

%INCLUDE{ "UsingAMainpage" level="-1" }%

-- PeterThoeny - 21 Feb 2005

rather than specifying a parameter for the inlcuded headings, why not just make them all relative to the location in the parent document they're being included into? So if they are included after a ---++ the included H1 becomes an H3?

-- MattWilkie - 21 Feb 2005

I think that the suggestion is better than the current behaviour. How about we introduce a flag and preference to disable the suggested new behaviour?

-- MartinCleaver - 13 May 2005

Which suggestion?

-- ArthurClemens - 13 May 2005

I recently brushedoff my LaTeX for some documents. One of the first things I did was create "dySection" commands to allow me to include other files and adjust the heading level.

-- AndyGlew - 24 Jun 2005

Is there anyone working on this? Or is there another means that this functionality has been implemented?

-- DanielHelsten - 05 Jun 2006

The direction I am headed towards is to include all of the wiki markup language, scan it, look for the highest heading level, and use that to adjust the heading level.


Level Including at Headngs In Text Effective Level
2 ---++ ---+, ---++ ---+++, ---++++
2 ---++ ----++ ---+++

I also need this to work for EmbedTopicPlugin

-- AndyGlew - 09 Jun 2006

Oh, yeah - I did not mean conditional inclusion. That's a separate topic. Here I just meant adjusting the header levels.

-- AndyGlew - 09 Jun 2006

As for work status - my current pet project is to convert wiki markup language to LaTeX, so that I can get a nicely formated document printed. I needs must do this header adjustment as part of this process, although, as already noted, I have my LaTeX dySection macros to do it for me.

By the way, if anyone has Wiki markup language to LaTeX, please tell me. I'm also considering plain old HTML or XHTML to LaTeX.

-- AndyGlew - 09 Jun 2006

anybody working on this feature ?

in my opinion an implementation of AndyGlew's proposal of 09 Jun 2006 E.g.

Level Including at Headngs In Text Effective Level
2 ---++ ---+, ---++ ---+++, ---++++
2 ---++ ----++ ---+++

would be the the optimal solution and would result in a big boost to the technique of INCLUDing Topics (unfortunately I'm not able to do this work by myself)

-- ThomasDoetterl - 10 Nov 2006

First, the spec should be further clarified.

E.g., what happens if you are in a section at level ---+++ and you are including text that is at level ---+? Should that become ---++++? What about if you include text that is at level ---++ and below. What should that become? My intuition says ---++++, but probably a good argument could be made for ---+++++ also.

Further, what should happen if text is included that is below a heading, but the %STARTINCLUDE% is after the heading? Does it get the level it has in the included topic or is it assumed to be outside all levels?

Depending how fancy this should be, we need something like the solution for NeedBeforeIncludeHandler.

-- ThomasWeigert - 13 Nov 2006

Auto-adjusting levels sounds useful. For compatibility I suggest to add an explicit flag, such as autoheadinglevels="on".

-- PeterThoeny - 13 Nov 2006

RE: ThomasWeigert - 13 Nov 2006
I think the machinery should be as simple as possible so I suggest

  • only look at the included "text" no matter how the context (i.e. the heading-structure) looks in the source-Topic
    => if the in the source-Topic excludes a heading -> ignore it
    • rationale: the author of the sourc-Topic explicitly did not want it to be included in other topics
      (by placing the )
  • the highest Level in the source-Topic should be adjusted to be one level under the current level in the destination-Topic
    this normally results in decrementing the heading-levels of the icluded text
    however, it could also result in incrementing it
    • rationale: the author of the destination-Topic deliberately places the INCLUDE-clause below a specific heading
      so the following "chapters" should be "sub-chapters" of this heading


destination-Topic source-Topic result
---+++ ---+ ---++++
---+ ---+++ ---++

-- ThomasDoetterl - 13 Nov 2006

I have implemented something simple, which may not solve all problems, but may be is a step in the right direction. Look at the patch for all the details, documentation (patch to VarINCLUDE) and demo in IncludeTest (name collision here!). The basics is that it just uses the proposed %EXTRA% hack, except you don't need to change the included document so it still can be used stand alone.

-- MarcSCHAEFER - 27 Nov 2007

Here's an easy to grasp spec that should do in most cases: All levels of headlines are relative to a root. On a normal topic view, the root starts counting at level zero. An include happens on a certain level of headlines and this becomes the new root for the included text.

So including a ---+ inside a ---+++ will result in the same header level ---++++ as the other way around.

IMHO, the depth of INCLUDEs should not be taken under consideration when computing the resulting level, as these might happen quite arbitrary.

-- MichaelDaum - 29 Nov 2007

considering the numbe rof times i've come across a topic that has no h1 and h2 headers 'because they looked too big' I agree with what Michael is saying:

the header depths should be brought in as relative, not absolute, with the lowest level in the INCLUDEd section being either the same as the current level they are brought in to, or one smaller.

This is probably time for a diagram, but I think I'll goto sleep instead.

-- SvenDowideit - 29 Nov 2007

I agree that relative is more useful than absolute. I'd go so far to use an offset, e.g. a %INCLUDE{ "SomeTopic" headingoffset="+2" }% changes H1 to H3, H2 to H4, etc. (I just realize that was already suggested inSupport.IncludingTopicButLoweringHeadingLevel.)

-- PeterThoeny - 03 Dec 2007

fix for the previously documented implementation

-- MarcSCHAEFER - 29 Jan 2008

This proposal has been lingering for a long time. I defined a spec (see above) and put myself as committed developer.

-- PeterThoeny - 2010-06-22

This is now AcceptedBy7DayFeedbackPeriod.

-- PeterThoeny - 2010-06-30

Now implemented and documented in SVN trunk.

-- PeterThoeny - 2010-07-07

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatdiff simple-include-offset-headings-v0.2.diff r1 manage 8.6 K 2007-11-27 - 23:18 MarcSCHAEFER Simple include offset headings, v0.2
Unknown file formatgz simple-include-offset-headings-v0.3.diff.gz r1 manage 2.6 K 2008-01-29 - 14:39 MarcSCHAEFER Simple headings offset patch, v0.3
Unknown file formatdiff simple-include-offset-headings.diff r1 manage 7.0 K 2007-11-27 - 15:51 MarcSCHAEFER Simple headings offset patch
Edit | Attach | Watch | Print version | History: r31 < r30 < r29 < r28 < r27 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r31 - 2010-08-21 - 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.