IMPORTANT: This plugin is still under development and may not always work as intended. Please test it and send feedback, but don't wonder if something doesn't work as expected, or even breaks after an update!

You can install the plugin using the Plugin Manager (look for “ad hoc”), or via the download URL above. Refer to Plugins on how to install plugins manually.

This plugin enables you to use the certain HTML tags directly in your DokuWiki code. By adding a simplified way of encoding attributes, this enables a more elegant and less verbose code, as in the following example:

The <dfn #lemma><i :la>Ad Hoc</i> Tags plugin</dfn> gives <b important>flexibility</b>
in using <abbr "HyperText Markup Language">HTML</abbr> tags, without the <u error>hasle</u> and potential
security problems of enabling full <abbr>HTML</abbr> input.

For more information, please see the Read Me file on GitHub.

The plugin adds the following tags to DokuWiki (links go to the MDN pages for these tags):

• <a> — “Anchor/Link”
• <abbr> – “Abbreviation”
• <address> – “Address”
• <article> – “Article”
• <aside> – “Aside”
• <b> – “Bring Attention To” (“bold”)
• <bdo> – “Bidirectional override”
  + <bdi> – “Bidirectional isolate”
• <cite> – “Citation”
• <details> – “Details”
  + <summary> – “Summary”
• <dfn> – “Definition ”
• <div> – “Generic block”
• <em> – “Emphasis”
• <figure> – “Figure”
  + <figcaption> – “Figure caption”
• <h1> … <h6> – “Section Headings”
• <i> – “Idiomatic Text” (“italic”)
• <kbd> – “Keyboard Input”
• <mark> – “Mark Text”*
• <q> – “Inline Quotation”
• <s> – “Strikethrough”
• <samp> – “Sample Output”
• <section> – “Section”
• <small> – “Side content” (“smaller”)
• <span> — “Content Span”
• <strong> – “Strong importance”
• <time> – “Date/Time”
• <u> – “Unarticulated Annotation” (“underline”)
• <var> – “Variable”

The plugin inherits some of the attribute syntax from the Wrap plugin, but adds functionality to some and more attributes via its own extended syntax.

Note: unless otherwise specified, the attributes can not contain any spaces.

• id adopts the CSS syntax, e.g. use #lemma to generate: id="lemma".

• Any valid class name is passed through to the class attribute. There can be an arbitrary number of class specifications in any tag.

• lang (language) uses the : syntax, as introduced by the Wrap plugin. For example, :fr becomes: lang="fr".
  This is fully compatible with BCP-47, i.e. you can also use specifications like :fr-BE (French as spoken in Belgium), or :grc-Latn (Latin transcription of Ancient Greek), etc.
  This also sets the dir attribute, unless there is another direction specified (see below for more information)

• title is simply any text that is enclosed in double quotation marks, for example: <abbr "HyperText Markup Language">HTML</abbr>. This attribute can contain spaces.

• Finally, there is a mechanism for additional “extended” attributes. These are marked by square brackets and either contain a name and value (e.g. [dir=rtl]), or for boolean attributes simply the name (e.g. [open]). More information below.

• The width format from the Wrap plugin is still available for compatibility (for example 75%, or 24em). This feature is considered deprecated because it is not compatible with the [style=…] extended attribute. Please use CSS – either inline or via classes – instead!

Note: the datetime syntax with an & prefix that was previously introduced is no longer available.

Extended attributes are marked by square brackets. They typically contain a name and the value, separated by an equals sign (example: [dir=rtl]) or in some cases “empty” attributes (e.g. hidden.

The following attributes are available in all tags:

• [dir=…] – Direction. This overrides any direction setting by the :lang attribute. Possible values are: rtl (right-to-left), ltr (left-to-right), or auto.

• [hidden] – Hidden. Temporarily hides the element and its content from view. This can be used as an empty element (without a value), or with the values hidden, or until-found.

• [tabindex=…] – Tab Index. Overrides the tabing behaviour of the element. It is recommended to only use the values -1 or 0. Only Integer values are allowed.

• [is=…] – Custom element. Allows to assign the element to a custom element class. See Using custom elements for more information.

• [style=…] – Inline Style. Allows to specify inline styles. This is still an experimental attribute that needs to be activated in the configuration, if you want to use it. Example: [style=color:red;text-decoration:underline].

• [data-*=…] – Custom data. Any attribute that starts with data- (e.g. data-value) is passed right through for custom data storage.

• [itemscope], [itemid=…], [itemprop=…], [itemref=…], and [itemtype=…] allow microformats to be embedded in HTML.

The following attributes are only available in specific tags:

• [open] – empty attribute that is only available in <details> tags. If specified, the section will be expanded by default.

• [datetime=…] specifies a date, time, period, or combination thereof in the <time> element. Can contain any valid ISO 8601 date format, including those that contain spaces!

• [href=…], [hreflang=…], [target=…] and [rel=…] can only appear in <a> tags.
  Note that javascript:-URLs are disabled by default in href attributes, but all other methods are available.

The configuration settings for this plugin allow you to select exactly which tags you want to allow and which to disable.

For example, you may want to disable the <span> and <div> tags, if you are also using the Wrap plugin, as there might otherwise be a conflict between these two plugins.

There are also two options to enable the experimental features mentioned above. These may be removed or changed in later versions. In the meantime, feedback is very welcome!

The plugin adds a new menu to the editor toolbar, which gives you direct access to most of the tags mentioned above.

This plugin does not introduce any CSS. The formatting is completely up to the template that you are using, or to your user stylesheets.

You should also be aware that some templates even overwrite the default styling for these tags (e.g. <q> is not behaving as it should in the default DokuWiki template). In these cases, you may need to reset these tags to their defaults in the user stylesheet.

A large portion of the code has been taken from the Wrap-plugin. Many thanks to all the contributors there for the great service to the community!

On my side, there are still a lot of issues to be fixed. I encourage everybody who might need something like this to test the plugin and send feedback and bug reports.

One of the main objectives of this plugin is to make the use of correct, semantic HTML tags available without compromising on the security of the installation.

However, there is a balance that has to be found between security and functionality. This particularly affects anything that may allow users to run custom JavaScript code.

There are two mechanisms for this introduced by this plugin: While the is attribute is limited to reference JavaScript that has been loaded outside of the scope of the user-editable content, the following example shows how a user may enter arbitrary code that is executed on mouse-click:
  <a [href=javascript:alert('Hello world!')]>.

On the other hand, there are many functionalities that the site admin may make available via this format – or a site may not have any user content anyways, and thus it is up to the site admin to allow such functions…

By default, javascript:-URLs are disabled in the plugin configuration. There may be good reasons to enable it for your site, but please don't do so unless you are aware of the dangers of allowing users enter arbitrary JavaScript code, even if it only runs when someone actually clicks on it.

Alternatively, please consider providing specialized custom-elements that your users can call on in the site content via the is attribute.