====== Entities ======

[[DokuWiki]] can replace certain characters or strings with other strings based on a configuration file. By default this is used to convert various character combinations to their typographical equivalent.

e.g.

<code>
<<  to « 
>>  to » 
=>  to ⇒
\_  to &nbsp;
</code>

see also [[wiki:syntax#text to html conversions]] on the syntax page.

=====Modifying/disabling some entity replacements=====
Details of the conversions are stored in the ''[[https://github.com/dokuwiki/dokuwiki/blob/master/conf/entities.conf|conf/entities.conf]]'' file. To avoid your changes being overwritten when upgrading Dokuwiki, you should place your own additions in a new file called ''conf/entities.local.conf''. 

If you need to //disable// some of the default conversions you could do it by adding only the pattern and //not// a replacement to ''conf/entities.local.conf''. Modifying can by reusing a pattern, but add your own symbol. The line there will take precedence over the one in the ''conf/entities.conf''. 

e.g. if you do not wish to have the letter c in brackets automatically replaced by the copyright sign <code - conf/entities.local.conf>
(c)
>> #or with comment explaining that entity is removed
</code>
or if you prefer another arrow <code - conf/entities.local.conf>
=>   ▶
</code>

For configuration changes to take effect on the pages, the [[devel:caching|cache must be purged]].


Even though by default it is used with simple character replacements only, the entity system can also be used to insert more complex constructs into your pages. This includes HTML. However you should be aware that doing so is bound to break when used in combination with non-HTML renderers (like [[plugin:ODT]] for example). It is recommended to use UTF-8 characters instead whenever possible.

Be sure to read about [[utf-8|UTF-8 Encoding]] before editing the config file.

===== Example configs =====

The entity mechanism can be used to adapt DokuWiki to some French typography rules that necessitate non-breaking spaces before or after some punctuation marks.
<code - conf/entities.local.conf>
<< &laquo;&nbsp;
? &nbsp;?
: &nbsp;:
! &nbsp;!
; &nbsp;;
>> &nbsp;&raquo;
</code>

To use typography for [[wp>esperanto|esperanto]] x-writing use the following:

<code - conf/entities.local.conf>
CX   Ĉ
cx   ĉ
GX   Ĝ
gx   ĝ
HX   Ĥ
hx   ĥ
JX   Ĵ
jx   
</code>

===== Using the number sign (#), not as comment =====

In ''conf/entities.local.conf'' the number sign ''#'' is used to start comments. If you want to use it as normal character, you have to escape it via backslash ''\#''. For example:

<code - conf/entities.local.conf>
~~noheader~~      <style> \#dokuwiki__header { display: none; } </style>
</code>

===== See also =====
  * [[config|Configuring DokuWiki]]
  * You can install and use the [[plugin:confmanager|{{https://raw.githubusercontent.com/cosmocode/confmanager/master/admin.svg?16}}]][[plugin:confmanager|Configuration File Manager]] for editing via admin interface of the wiki