1# DokuWiki Plugin Ad-Hoc HTML
2A secure but flexible way to insert HTML tags into DokuWiki
3
4This is an attempt to enable direct insertion of HTML tags in DokuWiki that is not reliant on the HTML option, which is no longer available in current versions of DokuWiki.
5
6More information on the [Plugin Page on DokuWiki](https://www.dokuwiki.org/plugin:adhoctags).
7
8## HTML Elements
9
10The following HTML elements are added by this plugin (in alphabetic order):
11
12- `<abbr>` – “[Abbreviation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr)”
13
14- `<address>` – “[Address](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address)”
15
16- `<article>` – “[Article](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article)”
17
18- `<aside>` – “[Aside](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/aside)”
19
20- `<b>` – “[Bring Attention To](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/b)” (also known as “bold”)
21
22- `<bdi>` – “[Bidirectional Isolate](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdi)” and `<bdo>` – “[Bidirectional Text Override](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdo)”
23
24- `<cite>` – “[Citation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite)”
25
26- `<details>` – “[Details](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details)” and `<summary>` – “[Summary](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary)”
27
28- `<dfn>` – “[Definition](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn)”
29
30- `<dl>` – “[Description list](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl)”, `<dt>` – “[Description term](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt)”, and `<dd>` – “[Description details](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd)”
31
32- `<div>` – “[Generic block](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div)”
33
34- `<figure>` – “[Figure](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure)” and `<figcaption>` – “[Figure caption](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption)”
35
36- `<header>` – “[Header](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header)” and `<footer>` – “[Footer](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer)”
37
38- `<h1>` … `<h6>` – “[Section Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)”
39
40- `<i>` – “[Idiomatic Text](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i)” (also known as “italic”)
41
42- `<kbd>` – “[Keyboard Input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd)”
43
44- `<mark>` — “[Mark text](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark)”
45
46- `<pre>` – “[Preformatted Text](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre)”
47
48- `<q>` – “[Inline Quotation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q)”
49
50- `<s>` – “[Strikethrough](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s)”
51
52- `<samp>` – “[Sample Output](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp)”
53
54- `<section>` – “[Section](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section)”
55
56- `<small>` — “[Side content](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small)” (smaller)
57
58- `<span>` — “[Content span](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span)”
59
60- `<time>` – “[Date/Time](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time)”
61
62- `<u>` – “[Unarticulated Annotation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/u)” (also known as “underline”)
63
64- `<var>` – “[Variable](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/var)”
65
66Please note that `<div>` and `<span>` are also handled by the [Wrap](https://github.com/selfthinker/dokuwiki_plugin_wrap) Plugin and having them enabled while Wrap is also active can lead to unexpected results. If you need the attribute features of this plugin with these tags, it is better to disable Wrap, and possibly use [Ad-Hoc Wrap](https://github.com/saschaleib/dokuwiki-plugin-adhocwrap) instead as a replacement.
67
68## Attributes
69
70Instead of specifying the attributes in the HTML format, this plugin replicates and expands the formats used by the **wrap** plugin, which allows to specify the attributes as in the following example:
71
72`<tagname #tagid csswidth :lang &datetime classname classname2>`
73
74- `#tagid` – any valid HTML id, prefixed by a hash (`#`) will be used as the element’s ID.
75
76- `csswidth` – a valid width specification, as used by CSS (examples: `50%`, `24em`, `460px`, etc.).
77
78  Note: This option is still included for compatibility, but it is generally not recommended because it can cause layout issues on smaller screens (e.g. smartphones).
79
80- `:lang` – a colon (`:`), followed by a valid [BCP47](https://www.rfc-editor.org/info/bcp47) language code. Examples: `:en`, `:fr-CH`, `:grc-Latn`, etc. See also: “[Declaring language in HTML](https://www.w3.org/International/questions/qa-html-language-declarations)”.
81
82  Note: this will also set the HTML `dir` attribute: either by setting a language code that has a default RTL script, or by appending a script tag that refers to a RTL script (e.g. `Arab` or `Hebr`). The resulting text direction can still be overriden by the `[dir=…]` attribute (see below)
83
84- `"Title text"` – A string that is enclosed in double quotes will be rendered as `title`.
85
86- `classname` – anything that does matches a valid CSS class name (and none of the other formats) will be treated as a class name.
87
88- `[name=value]` – extended format for all other allowed attributes. For example, `[style=color:red]`, or `[dir=ltr]` to override the text direction set by the `:lang` attribute, etc.
89
90Generally, attributes can appear in any order and are always optional!
91
92## Migration Notes
93
94If you previously used `<html>` tags to embed HTML code into your DokuWiki site, you need to replace them with the format used by this plugin. The best way to get started is to make a run a couple  of search-replace operations on the `data/pages/` directory in your DokuWiki installation.
95
96:bangbang: **Important:** It is advisable to run the following searches on a *copy* of this directory and also keep a backup of the original state, in case of problems that only show up later. The following search-replace operations can do serious damage to your site content. The autor does not take any responsibility for any damages that follow from applying this procedure: :bangbang:
97
98:information_source: **Tool:** The autor has made good experiences with the Search-Replace function of [Notepad++](https://github.com/notepad-plus-plus/notepad-plus-plus), an open-source, free and very powerful text editor for Windows. Other editors may of course also offer similar functionality.
99
100**1. Remove the *\<html\>* tags**
101
102- Search for `<html>`in default mode, replace with an empty string.
103- Search for `</html>`in default mode, replace with an empty string.
104
105**2. Remove the attribute name from *title="…"* attributes**
106
107- search for ` title="` (note the space in front!) in standard mode, replace with ` "` (space + quotation mark)
108
109**3. Format the language specifications (if needed)
110
111- Search for ` lang="([^\"]*)"` in *regex mode* (!), replace with ` :$1` (note: spaces in front of each!)
112
113**4. Simplify any *class*es**
114
115- Search for ` class="([^\"]*)"` in *regex mode* (!), replace with ` $1` (note the spaces again!)
116
117In most cases, these should take care of the vast majority of HTML attributes. Make sure to check each file and clean up anything that these searches didn't catch.
118
119If needed, similar searches can also be used for other attributes (e.g. ` style="([^\"]*)"` -> ` [style=$1]` for style), but it is probably a good idea to manually update these, rather than relying on automatisms.
120