How can I insert an image into a header in DokuWiki? I’m trying to create a header with an image, but the standard syntax doesn’t work. For example, I want to convert:
===== Header =====
{{:wiki:image.png?nolink|}} I want an image in the header
to a format where the image is directly inside the header:
===== {{:wiki:image.png?nolink|}} Header =====
Is there a way to include an image directly in a DokuWiki header?
Adding Images to DokuWiki Headers
In DokuWiki, the standard header syntax doesn’t support including images directly within the header text, but there are several ways to solve this issue using plugins and CSS styles.
Table of Contents
- Why Standard Syntax Doesn’t Work
- Header2 Plugin for Images in Headers
- Header3 Plugin as an Alternative
- CSS Solutions for Adding Images
- Practical Implementation Examples
- Recommendations for Choosing a Method
Why Standard Syntax Doesn’t Work
The standard DokuWiki syntax for headers doesn’t support markup inside the header itself. When you use the syntax:
===== Header =====
DokuWiki processes everything between ===== as plain text without additional markup. Attempting to insert an image using the syntax {{:wiki:image.png?nolink|}} directly in the header won’t work because the DokuWiki parser doesn’t apply wiki markup to header content.
As noted in the official DokuWiki documentation, headers have special processing and don’t support standard wiki markup within themselves.
Header2 Plugin for Images in Headers
The most effective solution is to use the header2 plugin, which allows you to apply wiki markup directly inside DokuWiki headers.
Installation and Activation
- Download the header2 plugin from GitHub
- Extract it to the
lib/plugins/folder of your DokuWiki installation - Activate the plugin through the plugin manager in your DokuWiki admin panel
Usage with Images
After activating the plugin, you can use the following syntax:
===== {{:wiki:image.png?nolink|}} Header =====
The header2 plugin supports the full DokuWiki image syntax, including:
- Internal images:
{{:wiki:image.png}} - External images:
{{http://example.com/image.png}} - Resizing:
{{:wiki:image.png?30x30}} - No links:
{{:wiki:image.png?nolink|}}
As noted in the header2 plugin documentation, this plugin is specifically designed to allow wiki markup inside headers.
Important: The header2 plugin changes DokuWiki’s XHTML renderer, which may affect compatibility with other plugins that also modify header rendering.
Header3 Plugin as an Alternative
Another option is the header3 plugin, which also supports wiki markup in headers and preserves line breaks as entered.
Functionally, header3 is very similar to header2, but with some differences in formatting processing. Installation and activation are similar:
- Download the header3 plugin
- Extract it to
lib/plugins/ - Activate through the plugin manager
The usage syntax will be the same:
===== {{:wiki:image.png?nolink|}} Header =====
However, as noted in the documentation, this plugin hasn’t been updated for over 2 years and may have compatibility issues with recent DokuWiki versions.
CSS Solutions for Adding Images
If you prefer not to use plugins, you can add images to headers using CSS. This method doesn’t place the image directly in the header text but visually achieves a similar result.
Method Using CSS :before Pseudo-element
Add the following CSS to your theme’s style.ini file or through custom styles:
/* For level 1 header */
h1:before {
content: url(:wiki:image.png);
margin-right: 10px;
vertical-align: middle;
}
/* For other header levels */
h2:before, h3:before, h4:before, h5:before {
content: url(:wiki:image.png);
margin-right: 10px;
vertical-align: middle;
}
As explained in the article about styling DokuWiki headers, you can use the :before selector to add images to all headers of a specific level.
Advantage of CSS approach: Doesn’t require installing additional plugins
Disadvantage: The image isn’t part of the header content and can’t be easily changed for different headers
Practical Implementation Examples
Example 1: Using header2 plugin
===== {{:wiki:icon.png?nolink|}} Introduction =====
===== {{:wiki:warning.png?nolink|}} Warning: Important Information =====
Result: Headers with icons to the left of the text.
Example 2: Different Images for Different Header Levels
===== {{:wiki:chapter.png?nolink|}} Chapter 1 =====
==== {{:wiki:section.png?nolink|}} Section 1.1 ====
=== {{:wiki:subsection.png?nolink|}} Subsection 1.1.1 ===
Example 3: CSS Solution with Different Images
h1.chapter:before { content: url(:wiki:chapter.png); }
h1.section:before { content: url(:wiki:section.png); }
Recommendations for Choosing a Method
| Method | Advantages | Disadvantages | Recommendation |
|---|---|---|---|
| header2 plugin | Full wiki image support, easy to use | Requires plugin installation, possible conflicts | Best choice for most cases |
| header3 plugin | Preserves line breaks | Not updated, less functionality | Alternative if header2 doesn’t work |
| CSS styles | No plugins needed, flexible configuration | Image isn’t part of content | For simple cases or when plugins can’t be used |
Summary: To insert images directly into DokuWiki headers, it’s recommended to use the header2 plugin, which is specifically designed for this purpose and supports the full DokuWiki image syntax. If for some reason header2 isn’t suitable, you can use CSS styles to visually add images to headers.
Sources
- DokuWiki Header2 Plugin Documentation
- DokuWiki Header3 Plugin Documentation
- DokuWiki Styling Headers Tips
- DokuWiki Wiki Syntax Documentation
- GitHub Header2 Plugin Repository
- DokuWiki FAQ: Header Links
Conclusion
- Standard DokuWiki syntax doesn’t support images in headers, but there are effective solutions
- header2 plugin is the most reliable way to add images directly inside headers
- Alternative methods include the header3 plugin and CSS styles for visually adding images
- It’s recommended to start with the header2 plugin as it provides the best functionality and ease of use
- For each type of header, you can use different images, creating a more visual document structure