====== hiddenheader Plugin ======

---- plugin ----
description: Create invisible section headers. Useful companion to the include plugin.
author     : Eli Fenton 
email      : elifenton@this_is_not_a_real_email.fake
type       : action
lastupdate : 2024-02-10
compatible : angua, rincewind, weatherwax, binky, ponder stibbons, hrun, detritus, Frusterick Manners, greebo, Hogfather, Igor, Jack Jackrum, Kaos
depends    : 
conflicts  : 
similar    : 
tags       : section, header, include, title

downloadurl: https://github.com/zioth/dokuwiki_hiddenheader/archive/master.zip
bugtracker : https://github.com/zioth/dokuwiki_hiddenheader/issues
sourcerepo : https://github.com/zioth/dokuwiki_hiddenheader
donationurl: 
----

This plugin allows you to create a section header which doesn't appear in the page. Why would you ever want to do this? Mainly to work with plugins that affect sections. You can also use it to set the page title without having a visible header, but the [[plugin:meta|meta plugin]] does that better.

I made this as a companion to the [[plugin:include|include plugin]]. Include lets you include a page or a section, but it's missing a feature I consider very useful -- the ability to include an excerpt from a large document which is not annotated with section headers.


===== Examples/Usage =====

Once the plugin is installed, you can create section headers with the special tag "%hide" in the title. The reference for the header is whatever comes after %hide. For example:

<nowiki>====%hide myhidden ====</nowiki>

In this case, the header will not show up in your page, but it will still be possible to link to pagename#myhidden (as with the [[plugin:anchor|anchor plugin]]). Additionally, other plugins will recognize this as a section called "myhidden." For example, using the [[plugin:include|Include plugin]], you can include the contents of this section as follows:

<nowiki>{{section>mypage#myhidden}}</nowiki>

Make sure to end the section, by starting a new section. This can be done with another hidden section, or with an empty section header: <nowiki>==== ====</nowiki>

Here's a complete example:
  This page is called "mypage."
  ====%hide myhidden====
  This text will show up if you use the include plugin on this section -- {{section>mypage#myhidden}}.
  ==== ====
  This text will not show up when using the include plugin.

This plug-in has one more use: Creating a title for a page that should not have a visible section header. For example, if you create the folowing as the first section in the page, wiki links to that page will show up with the header text as the title.

This: <nowiki>====%hide My Magic Page ====</nowiki>

in a page called somens:mypage causes this: <nowiki>[[somens:mypage]]</nowiki> to show up like this: My Magic Page.

Note that the [[plugin:meta|meta plugin]] does this invisible-title thing better, but if you're already using this plugin and don't want to install meta, you might as well take advantage of the feature.


===== Bugs/Issues =====

Looking at the code, I feel like this is pretty inefficient, since it involves multiple scans through the entire contents of the page. However, I haven't noticed any slowdown. If someone has an idea of a more efficient way to do this, let me know.

When an entire page containing these headers is included with the [[plugin:include|include plugin]], the headers will show up in the table of contents. That will not happen when just the section is included.

In Anguna, hidden headers show up in the table of contents. This took some time to work out in the last version. I'll see what I can do.

==Change Log==
  * 2018-12-31: Fixed some long-standing bugs.
  * 2013-05-22: Updated for Weatherwax. The new DokuWiki doesn't add anchors to headers unless there's a TOC.
  * 2012-03-29: I just ran into a case where the preprocess command could be called twice by dokuwiki. This might be a bug in Angua. The new code works around this problem.
  * 2011-08-26: Hidden headers are no longer added to the table of contents.
  * 2011-08-29: Updated license to GPL (requested by Anika Henke).

===== Discussion =====

Thanks, but I have a little problem (Mar2017, Frusterick).  When I link to a hidden section from another page, the hidden headers are shown on the page when I arrive.  The only way to hide them again appears to be to edit the page, make an actual change, and save.