Guidelines for Theme Developers
Intro
There seems to be some confusion about how a plugin theme should be made because the way h1 heading is handled was changed in moin 1.5.0beta1 and some theme developers didn't notice it or were confused about it.
This page documents how you should do it for themes for moin 1.5 and later.
In our examples we use the WikiSandBox as an example page.
Guidelines
Have a clear distinction between content and navigation
Content, displayed in content area, is directly determined by the wiki (or other) markup the user enters.
E.g. if a user enters this into WikiSandBox:
= The Wiki's Sandbox, a nice place to play = == What you can play here == ...
Then the first h1 and h2 headings of that content will be just that.
Navigation, displayed in navigation area, is to help the user navigate through the wiki, this includes:
- knowing where you are currently
- knowing where you came from
- knowing where to go to
Knowing where you are of course means to display the page name WikiSandBox somewhere in the navigation area.
Note that this WikiSandBox in the navigation area is not intended to look like a heading. Headings are content and you use heading markup to define them in your content. Thus the page name should rather be separated somehow and look different than a heading.
As a non-wiki parallel look at how some people do their wordprocessor documents: they have some content, but sometimes also (often in a tiny font in some corner) display the filename of it so they know where to find them on disk.
The wiki pagename is like that filename - good to know, but not related to content rendering.
For a wiki-like themes, the pagename display is important for navigation - so even though it is not a heading, it will be shown rather big at a prominent place (see modern theme).
For the read-only view of CMS-like themes, the pagename could be rather unimportant (the user is only using the site in a read-only manner and does not have to know the page name) and be displayed in a rather tiny font in the corner (or not at all). The read-write view of such a theme (only used by some few editors) could show the pagename in a bigger way, for better comfort while writing content.
Some themes (e.g. modern) use an even more comfortable way of showing where your are: Location breadcrumbs. It renders he current page name WikiSandBox/MySubSandBox/Testing in a way so that each fragment is clickable and either links to a parent page or to backlinks search (last fragment).
If you use a wiki farm, knowing where you are also includes knowing the name of the wiki you are currently viewing. Since 1.5, this can be enabled with show_interwiki = 1 and shows the interwiki name of the current wiki and links it to page_front_page. See the MoinMoin: in front of the page name in the navigation above.
Knowing where you came from is done by the Path breadcrumbs (or in moin slang: the trail) - it displays which pages you visited before.
Knowing where to go to is done by the navigation bar (navi_bar) which points to some important pages in the wiki.
Coding your <theme>.py
Most of the code you need is already written, just inherit from ThemeBase class (see MoinMoin/theme/__init__.py) and either use it as is or override what you need different.
Updating a pre-1.5 theme
- sync modern/css/screen.css #pagelocation #pagetrail stuff to your screen.css or pagelocation display (title()) will look strange (like a list).
- remove "#title h1 ..." CSS (or any other CSS assuming h1 is a page title and not just a first level heading), it is not used any more.
we now render = heading = as <h1> (was <h2> before 1.5), == heading == as <h2> (was <h3>), etc.
- maybe move both title() and trail() to header area, like the builtin themes do it.
- there is a new interwiki() base theme method that optionally (if show_interwiki = 1) shows the interwiki name of this wiki and links to page_front_page. The css for it is #interwiki.
How it was in moin < 1.5 and why it was changed
Older moins took the pagename and auto-generated a h1 heading in the content area from it.
The content headings started from h2. = A = was a h2 heading, == AA == was a h3 heading.
This magic had some problems:
often you don't want to have the (technical) pagename as your content's h1 heading (you also don't want letter.doc as h1 heading in some letter your write in your word processor).
- thus there was a feature requests for overriding this magic by a processing instruction to put their own h1
- in some other cases, you don't want any h1
- thus there was a feature request to override this magic and suppress the h1 completely
- you only can have a single h1 heading, no way to generate more headings of this level
there was no feature request for that, but sooner or later, there if we had gone that route, I am rather sure there could have been one.
- the h1 magic was often not wanted for print view
Looking at all that magic mess and more magic being requested to handle the mess, the decision was made to drop all h1 magic (instead of introducing more magic to handle what it does wrong):
- remove magic h1 generation in content area from the page name
- if you want a h1 in content area rendering, write it into your content!
shift heading levels so that = A = is a h1 heading, == AA == is a h2 heading (heading level == number of =-chars)
display the pagename in the navigation area - where it ever belonged to
This solved all the h1 magic related problems, but it has a price:
- theme developers need to change their themes accordingly for moin 1.5+
- if you want a h1, you have to put it in your content
people now often use wiki level one heading e.g. = This is a nice pagename = (also currently output as html h1 heading) to make a page title which is different from the original, cryptical underlying page name (e.g. NicePage). However this produces another bulk of problems e.g. messes up the table of contents and section numbering. See FeatureRequests/ExcludeHeadingsFromTableOfContent for a description and discussion.
There is some information about this problem at GoogleDoctype:ArticleSemanticsOfH1