Handling Page Headings/Titles/Names

There are multiple possibilities to handle the page name / page title / first h1 heading in a wiki engine.

MoinMoin changed the strategy with version 1.5.0, but some of the default content and some of the themes were not yet adjusted accordingly.

This is a place for discussion, not official guidelines (see ThemeGuidelines), feel free to use this page as you like.

Terms used in this page

page name

the name used to store and wiki-link the document, e.g.: WhyWikiWorks

page url

typically derived from the page name for example: http://example.com/wiki/WhyWikiWorks

page title

the title of the document, e.g.: "Old News: Why Wiki Works!". Traditionally, the page title is the page name. Some wikis add spaces to page names in the title to make theme more readable.

This is not the html title element, although typically the html title element contains the page title. When automated tools process a page, they look for the page title. For example, when you submit a link to reddit.com, the page title is used as the default title.
The page title is typically displayed in html h1 element
This page has a page title of Handling Page Headings/Titles/Names as defined by the first h1 in the page content

heading

a multi-level element (h1..h6 in html) you use to describe what some (following) (sub)section of the document is about

navigation area

output generated by the theme to ease navigation for the user

content area

output generated from content the user typed into the document

Heading is explicitely stated in the page contents

This is the MoinMoin default with the "modern" theme since 1.5 (also done this way by Trac wiki engine).

The user puts a single = Why Wiki works! = heading in his content and this generates the top h1 heading. Whether this is the only h1 heading (and everything else is h2+) is the user's decision (it is content - your content!). You can also choose to not have any headings at all on your page, e.g. on the RecentChanges page, you might want to have as much space as possible for the rc table.

Advantages are:

the page contents are clearly separated from navigation
- I don't see how it effect the separation, and why the separation is needed
h1 heading is under full user control done with normal heading markup without requiring additional processing instructions / other hacks
- = h1 heading =, == h2 heading == not = h2 heading =, === h3 heading ===
- May be considered a disadvantage, as it leads to inconsistent interface - some pages have a title some don't. From accessibility pov, each page should have a h1 title.
Web CMS-like themes that emphasize content over navigation (little or no navigation) work better. Page titles/heading created from page names are restricted by OS and file names rules. Page titles created by h1 headings may be formatted with blanks, special characters and can be pretty. Wiki-literate users will easily put up with crappy looking page titles because they understand why it is a crappy page title. Think about page content that stands on its own and a theme that eliminates all the wiki navigation and replaces it with a top or sidebar menu linking to the important pages of that site. The (wiki-illiterate) public could surf a wiki and never realize it is a wiki. With acl rules and an administrator to promote pages/changes to public status, Moin becomes a powerful Web CMS. The clear separation of page content from wiki navigation is a strategic move and opens the door to new applications.
- Page name are generally not restricted by OS and file systems because moin uses file system quoting. You can use any unicode character you like on any OS and file system. The only limit is the length of the name, which is about 40 character for assian languages (4 bytes per character), about 63 for Hebrew (2 bytes per character), and 254 for most roman languages - this limit comes from the max. filename length as moin currently stores the complete page name (including parent pages) as a single directory name. On Windows, the limit may be the maximum path length, which is 256 characters. The limit is in Windows APIs, NTFS supports extremely long path. There is modern_cms theme that worked nicely on 1.3 without with autogenrated titles, there is no need to move the title into the page content to use the wiki as a CMS.
  - If you try to use Handling Page Headings/Titles/Names as a page name, then doesn't the title method in ThemeBase treat Handling Page Headings and Titles as parent pages and create backlinks to non-existent pages? I agree that in most cases the page name could be manipulated (or not) to create an acceptable title. Per Wikipedia, I should have used the term "Web Content Management System" above. My wiki tries to explain a web based application to computer illiterates. A common problem with my users is they become confused after clicking on a wiki navigation link without understanding what a wiki navigation link is. A thought is a Web CMS theme would help the beginners learn about the application without first having to learn about wikis. We are far from the original thought that themes that emphasize content over navigation will work better if all page content is defined within the wiki page (and the page name does not trickle into the content as a heading). I am willing to withdraw the claimed advantage.

Short Term Disadvantages are:

creates a conversion workload for any existing moin wiki pages without h1 heading above all other content (some pages may not need h1 headings)
- Why some pages may not need a h1 heading? What will a screenreader user do when he find a page without a title? How can he navigate the page or understand what is this page about? To make the system accessible, it should have consistent and predictable structure.
creates a conversion workload for some theme developers to update their themes

Long Term Disadvantages are:

Confusion when searching for a page. You remember that page about Foo and Bars, but you cannot find the page in a title search, because the real page is actually named Baz.
The real page title is not available to page lists, title searches and html title element. Possible to fix by caching the value after the page is parsed.
A user may create confusing title, that looks like a sub page name - see the title of this page: "Handling Page Headings/Titles/Names" - Does "Handling Page Headings" exists? What about "Handling Page Headings/Titles"?
- A heading is a heading is a heading. Content is not navigation. If you see a big picture of a car, you have to live with it that you can't drive it, because it is a picture, not a car.
- And btw, wrong expectations due to things that have been done wrong in the past doesn't mean it is a disadvantage of the current method. So I suggest you remove this item again.
  - Some people think the page title is navigation and not content and that it was done right in past
    - See terms definition at top of this page. Of course a heading is NOT wiki navigation, but we misused the first h1 heading for navigation in the past. If you look at the other headings (h2..h6), you see that they are definitely not wiki navigation, they are just some words to structure the content of the page.
    - who cares about "content" and "navigation"? there are links in the text which provide (hyptertext) navigation as well. that is web. and the original wikis defined: if you click on the page heading the wiki software will tell you who points to the page.

I think making the change was a good design decision and will work well once everyone understands it and finishes the conversion work. However, the classic and modern themes should be reviewed as well. Making the fonts for the page names a tad smaller will improve the appearance. The large fonts seem to shout and compete with the h1 heading on properly designed pages.

First h1 heading is autocreated from the page name

This was the MoinMoin default up to v 1.5.0beta1 and of the original wikis like http://c2.com/cgi/wiki, http://mediawiki.org. Some of the wikis like mediawiki require explicit linking, which gives more "natural" page names, and some support additionally CamelCase linking, which allows to type less at the expense of the somewhat artificial page name.

Advantages:

Known from many wikis
Easy navigation - pagename is h1 heading is page url. You will never search for the page with heading "History of Foos and Bars", to find that the page name is barbaz (handling of whitespace is not related to this).
The real page name is available everywhere, for example, search results, page lists and in the html title element.
Don't mess with the table of contents - you don't want the title in the toc.
More freedom to the theme designer - complete control over page title design, without adding special markup in the page. The designer can control screen, print and projection headings.
Compatible with existing content created using version 1.3, which does not include a heading in the page itself. No need to convert exiting content.
Easy to use - you don't have to add a h1 heading, it is already there

Disadvantages:

If you want different h1 heading, you need special processing instructions.
Since page heading created from pagename used h1 element, markup created headings started with h2 and required the = this is not h1 = magic. However, this is not really a problem, you can easily design bigger h2 with css, and a wiki does not really need the full range of h1-h6. Wiki is not a system for creating complicated technical documents, but a system to allow quick and easy collaboration.
"Double titles" on historic content created with version 1.2 and earlier, does contain heading in the page itself, because the classic design used a separate heading in the site navigation area, which does not look like a heading.
If you want to disable the h1 heading, you would need special processing instruction like pragma.

Disadvantages avoided by proposal below:

You must change the page name (and url) if you want to change the h1 heading. Changing URLs should be avoided.
If you want nicer h1 heading with spaces, you'll get uglier url with %20/underscores
Less freedom for the wiki user - no control over page title design (the theme controls it).
Different from the model the common user knows. For example, in a word processor, the file name and title are not the same. You can change the file name or the title without affecting the other.
On some configurations (Apache mod_rewrite), it is not possible to use question mark in urls, so also not in the page name. This is rare problem but annoying when you like such page name. Systems that separate the page title from the page url does not suffer from this problem.

First h1 heading is autocreated from page name plus alternative option

This is easy to implement in MoinMoin by using special pragma. I don't know other wikis that implement that. The behaviour is like "page name headings", but there is an option of stating a configurable heading in the metadata:

#pragma heading Guidelines for Theme Developers

This heading is not part of the contents but is a traditional auto-generated wiki navigation heading. Additionally the content author is given a means to set a heading which is different from the page name or to suppress the heading completely:

#pragma heading

Advantages:

if the users knows nothing about it, its "autocreating heading from pagename"
allows both worlds, i.e. pagename, and custom text as page heading
guarantees that there is at least one h1 heading above the content

Disadvantages:

same as of proposal "autocreating heading from pagename", except that here you may override the heading with a custom text which may be set to empty - and therefor avoids a number of problems stated above
more complex for the user (only if she uses the pragma of course) and also more complex to handle in the code

Questions:

can it be configurable if "= =" gives a h1, or a h2?
- Theoretically everything can be configurable, but too much configurability only does harm due to unpredictable behaviour. For example, if a user uses multiple moin wikis (and also for MoinMoin support). You just have to fix your themes and your content.

Accessibility considerations

From an accessibility's point of view - especially from a screenreader user's point of view - it would be nice, if html-element h1 headings would be reserved for hidden metastructuring of the whole wiki page (including content, editbar, navigation...). This means: in html-output (and only there) the html-formatter outputs wiki level one headings (=Blablabla..=) as html level two headings (<h2>Blablabla</h2>). Why this? Because most screenreaders do have special shortcut keys to jump quickly from heading to heading. If the whole wikipage-output would be structured like this, navigation would be super easy for screenreader users:

<h1> Navigation menu </h1>
- <h2> Your are here: breadcrumbs navigation</h2>
- <h2> Important links + user-defined quicklinks ... </h2>
- <h2> Trail </h2>
<h1> Edit and actions menu </h1>
- ...
<h1> User's menu </h1>
- Login
- Perfernces
- Homepage
<h1> Page content </h1>
- <h2>Blablabla</h2> i.e. your pagename or your heading
- other wikimarkup level 1 heading...
<h1> Footer (with Contact information, disclaimer...) </h1>

Something like this has been implemented in ThemeMarket/SimpleMente. Please note: these h1 headings metastructuring the whole page output need not be visible to normal users but only to screenreader user! Check out Simplemente for that: you have a nice theme that looks compelling (of course that's a matter of taste..). Now turn of >css< in your browser so that you can see how people "see" the theme using a screenreader. Compare Moderne theme and Simplemente with css turned off. Hidden h1 headings are a big step forward in accessibility. Simplemente even tried to reorganize the structure of a page so that the content appears as fist h1 heading. However doing this is a little bit shaky and does not work on older browsers.

Here is a simpler layout using accessible h1 elements:

skipto: content, navigation, search, user, actions, info
<h1>bread / crumbs / title</h>
- page content here...
- <h2>user headings</h2>
- More text...
<h1>navigation</h1>
- links to main wiki pages...
<h1>search</h1>
- search form
<h1>user</h1>
- user links, login/logout preferences etc.
<h1>page actions</h1>
- edit, subscribe...
<h1>info</h1>
- information about this revision

The title can function as location bread-crumbs. Here is a nice example and another one (and from now on: also ThemeMarket/SimpleMente ).

This layout is also more search engine and text mode browser friendly, sending the content before the navigation. Components are positioned using CSS.