====== Ad-Hoc HTML Plugin ======

---- plugin ----

description: A secure but flexible way to insert HTML tags into DokuWiki
author     : Sascha Leib 
email      : sascha.leib@kolmio.com
type       : Syntax
lastupdate : 2025-05-14
compatible : Librarian, Kaos, Igor, Jack Jackrum
depends    : 
conflicts  : 
similar    : wrap
tags       : html, syntax

downloadurl: https://github.com/saschaleib/dokuwiki-plugin-adhoctags/archive/refs/heads/main.zip
bugtracker : https://github.com/saschaleib/dokuwiki-plugin-adhoctags/issues
sourcerepo : https://github.com/saschaleib/dokuwiki-plugin-adhoctags
donationurl: 

screenshot_img : https://fallacies.online/img/AdHocTags.png
----

**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.

===== Installation =====

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

===== Examples/Usage =====

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:

<code xml>
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.
</code>

For more information, please see the [[https://github.com/saschaleib/dokuwiki-plugin-adhoctags/blob/main/README.md|Read Me]] file on **GitHub.**

===== Syntax =====

==== HTML Tags ====

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

  * ''<a>'' — “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a|Anchor/Link]]”
  * ''<abbr>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr|Abbreviation]]”*
  * ''<address>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address|Address]]” 
  * ''<article>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article|Article]]” 
  * ''<aside>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside|Aside]]”*
  * ''<b>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/b|Bring Attention To]]”* (“bold”)
  * ''<bdi>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdi|Bidirectional isolate]]”
  * ''<bdo>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdo|Bidirectional override]]”
  * ''<cite>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite|Citation]]”
  * ''<details>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details|Details]]” \\ + ''<summary>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary|Summary]]” 
  * ''<dfn>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn|Definition]]”
  * ''<div>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div|Generic block]]” 
  * ''<dl>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl|Description list]]” \\ + ''<dt>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt|Description term]]” \\ + ''<dd>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn|Description details]]”
  * ''<em>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em|Emphasis]]”
  * ''<figure>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure|Figure]]”* \\ + ''<figcaption>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption|Figure caption]]”* 
  * ''<header>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header|Header]]”
  * ''<h1>'' … ''<h6>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements|Section Headings]]”
  * ''<hgroup>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hgroup|Heading group]]”
  * ''<footer>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer|Footer]]”
  * ''<i>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i|Idiomatic Text]]”* (“italic”)
  * ''<iframe>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe|Inline frame]]”
  * ''<img>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img|Image]]”
  * ''<kbd>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd|Keyboard Input]]”
  * ''<li>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li|List item]]”
  * ''<mark>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark|Mark Text]]”*
  * ''<menu>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/menu|Menu list]]”
  * ''<ol>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol|Ordered list]]”
  * ''<pre>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre|Preformatted]]”
  * ''<q>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q|Inline Quotation]]”*
  * ''<s>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s|Strikethrough]]”*
  * ''<samp>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp|Sample Output]]”
  * ''<section>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section|Section]]”*
  * ''<small>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small|Side content]]” (“smaller”)
  * ''<span>'' — “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span|Content Span]]”
  * ''<strong>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong|Strong importance]]”
  * ''<time>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time|Date/Time]]”
  * ''<u>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u|Unarticulated Annotation]]”* (“underline”)
  * ''<ul>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul|Unordered list]]”
  * ''<var>'' – “[[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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 [[plugin:wrap|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 [[plugin:adhocwrap|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 [[plugin:adhoctables|Ad-Hoc Tables]] plugin in addition to this one.

There is also an extension to this plugin that enables [[wp>MathML|MathML]] tags. Please see: [[plugin:adhocmathml|Ad-Hoc MathML]].
==== HTML Attributes ====

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 [[https://www.rfc-editor.org/info/bcp47|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 ====

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=…]'' – [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/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]'' – [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/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=…]'' – [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/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=…]'' – [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/is|Custom element]]. Allows to assign the element to a custom element class. See [[https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements|Using custom elements]] for more information.

  * ''[style=…]'' – [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/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-*=…]'' – [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*|Custom data]]. Any attribute that starts with ''data-'' (e.g. ''data-value'') is passed right through for custom data storage.

  * ''[aria-*=…]'' – [[https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics|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 [[https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemscope|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 [[wp>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.

  * ''[src]'' – source for ''<iframe>'' and ''<img>''-elements.
  * ''[width=…]'' and ''[height=…]'' – dimensions for ''<iframe>'' and ''<img>''-elements.
  * Several other specialized attributes for both ''<iframe>'' and ''<img>''. Please see the MDN docs for details.

===== Configuration and Settings =====

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 three options to enable the experimental features mentioned above. These may be removed or changed in later versions. In the meantime, feedback is very welcome!

===== User Interface =====

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

==== CSS ====

This plugin does //not// introduce //any// CSS. The formatting is completely up to the template that you are using, or to your [[devel:css|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.

===== Development =====

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.

===== Security =====

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.

===== Hint: Switch from HTML =====

Using the [[plugin:batchedit|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''^
|<code><\/{0,1}html></code>| |remove html tags|
|<code> title="</code>|<code> "</code>|remove title|
|<code> class="([^\"]*)"</code>|<code> $1</code>|remove class|
|<code> lang="([^\"]*)"</code>|<code> :$1</code>|remove lang|
|<code> style="([^\"]*)"</code>|<code> [style=$1]</code>|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.

[[https://forum.dokuwiki.org/d/20975-how-to-replacing-htmlok-or-phpok-with-similar-capability/6|This is explained in more detail here.]]

//I have added this section, but perhaps it should go somewhere else.  --- [[user>saggi|saggi]] //2023-05-17 15:49////