Compatible with DokuWiki

• 2024-02-06 "Kaos" yes
• 2023-04-04 "Jack Jackrum" yes
• 2022-07-31 "Igor" yes
• 2020-07-29 "Hogfather" unknown

• Download
• Report bugs

A secure but flexible way to insert HTML tags into DokuWiki

Last updated on

2023-10-14

Provides

Syntax

Repository

Source

Similar to wrap

Tagged with html, syntax

Needed for adhocmathml, adhoctables, adhocwrap

By Sascha Leib

Note: This plugin was formerly known as “Ad Hoc Tags”. It is being renamed in order to avoid confusion with other “tags” plugins here, which all do something entirely different.

You can install the plugin using the Extension 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>
syntax.

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”)
• <bdi> – “Bidirectional isolate”
• <bdo> – “Bidirectional override”
• <cite> – “Citation”
• <details> – “Details”
  + <summary> – “Summary”
• <dfn> – “Definition”
• <div> – “Generic block”
• <dl> – “Description list”
  + <dt> – “Description term”
  + <dd> – “Description details”
• <em> – “Emphasis”
• <figure> – “Figure”*
  + <figcaption> – “Figure caption”*
• <header> – “Header”
• <h1> … <h6> – “Section Headings”
• <footer> – “Footer”
• <i> – “Idiomatic Text”* (“italic”)
• <kbd> – “Keyboard Input”
• <mark> – “Mark Text”*
• <pre> – “Preformatted”
• <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”

Note that only a selection of these tags (marked here with an *) is enabled by default after installation. Please go to the configuration settings to enable other tags that you need for your site.

Important: The <div> and <span> tags are also handled by the Wrap-plugin. If both the Wrap-plugin and these tags are active, this can lead to unexpected results. If you want to use <div> or <span> and still have access to selected features of the Wrap plugin, please consider using Ad-Hoc Wrap instead of Wrap.

Note that HTML table tags have deliberately been omitted from this plugin. If you need these, please install the Ad-Hoc Tables plugin in addition to this one.

There is also an extension to this plugin that enables MathML tags. Please see: Ad-Hoc MathML.

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 that was inherited from the Wrap plugin has been removed in the latest version. Please use CSS instead – either inline (see below) or via classes!

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. Note that the dir attribute is also controlled by the language setting (see above), but an explicit [dir=…] specification will always override the language direction.

• [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 (any other value is discarded).

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

• [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.

• [aria-*=…] – WAI-ARIA. Any attribute that starts with aria- (e.g. aria-label) is passed through for accessibility settings.

• [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=…], [rel=…] and [download=…] can only appear in <a> tags.
  Note that javascript:-URLs are disabled by default in href attributes (they can be enabled in the configuration), but all other methods are available, provided the <a>-tag itself is enabled, of course.

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.

Using the Batchedit plugin, switching to this plugin is relatively easy. After installing the Batchedit plugin you can use it from the admin page.

Always use the regex mode

Namespace - can be left empty (all) or limit the found pages

Note the leading spaces
Search for	Replace with	Edit summary
<\/{0,1}html>		remove html tags
title="	"	remove title
class="([^\"]*)"	$1	remove class
lang="([^\"]*)"	:$1	remove lang
style="([^\"]*)"	[style=$1]	change style

After each search term, use the preview function and select the pages to be replaced. Then Apply and edit the next search term.

This should replace the normal uses (styling) of HTML. For javascript in HTML tags users this is not suitable.

This is explained in more detail here.

I have added this section, but perhaps it should go somewhere else. — saggi 2023-05-17 15:49