---json
{
    "canonical": ":link",
    "description": "The link component permits to create hyperlinks between pages.",
    "low_quality_page": "false",
    "name": "Links",
    "page_id": "0oocdu2rx6z4pyfb3un4w"
}
---
====== The Link component ======

===== About =====
''link'' is  a [[docs:component|ComboStrap UI component]] that permits to create hypertext link to page or media and allows any syntax inside. You can therefore have an [[#icon|icon link]]



===== Type =====

==== Internal ====

An ''internal'' link is a link from a page of your [[docs:app:app|website]] to another page of your [[docs:app:app|website]].

If the target page does not exist, the link is shown in ''red''. You can even use the [[docs:styling:styling|styling attributes]]

  * Example:
<webcode name="Default" frameborder=0>
<code dw>
Links to [[#|existing pages]] are shown in a different style from [[nonexisting|nonexisting]] ones.

Internal Links can also be [[?color=#495057|styled]]
</code>
  * Result:
</webcode>

<note>
  * The default description if not set is the [[docs:page:name|page name]] for [[docs:navigation:navigation|navigational component]], the [[docs:page:title|title]] otherwise.
  * The URL may be made [[docs:page:url|permanent by adding the page identifier]].
  * A relative link path (without the first character `:`) is relative to the slot (ie a link in a footer slot will be relative to the footer).
</note>


==== External ====

An ''external'' link is a link that begins with ''http'' or ''https''.

  * Example:
<webcode name="Default" frameborder=0>
<code dw>
External link to our protected page [[https://combostrap.com/quality/low_quality_example|low quality page]]
</code>
  * Result:
</webcode>
==== Interwiki ====

An ''interwiki'' page is a shortcut syntax that permits to create rapidly a link to another website. The host is replaced by a ''wikiName'' (ie website name)

Syntax:
<code html>
wikiName>path?query#fragment
</code>

For instance:
  * to [[doku>|Dokuwiki]] syntax
<webcode name="Default" frameborder="1">
<code dw>
Interwiki: [[doku>Interwiki]]
</code>
  * to [[doku>|Dokuwiki]] Result
</webcode>
  * to [[wp>|wikipedia]] syntax
<webcode name="Default" frameborder="1" >
<code dw>
The ''publication'' article link can be created with this syntax: [[wp>publication]]
</code>
  * to [[wp>|wikipedia]] result
</webcode>


==== Email ====


===  Email addresses ===

<webcode name="Default" frameborder=0>
<code dw>
<support@combostrap.com>
</code>
</webcode>
=== Email link ===
If there is no description, the email is shown with the [[doku>config:mailguard|visible protection]].
<webcode name="Default" frameborder=0>
<code dw>
[[support@combostrap.com?subject=Contact via WebSite]]
</code>
</webcode>

=== Email Protection ===


Email protection against bots is almost a lost cause but you can give them an hard time with this [[doku>config:mailguard|mailguard configuration]].


<note>
Note that the ''hex'' value is only valid for email written in text and not in link. If this is the case, the protection is set to ''visible'' replacing the ''@'' with its textual counterpart (ie '''at'')
</note>


==== Windows Share ====

<webcode frameborder=0>
<code dw>
Windows Shares: [[\\server\share|this]]
</code>
</webcode>
==== Image ====

You can add an [[docs:content:image|image]]
<webcode name="Default" frameborder=0>
<code dw>
[[:start|{{:apple-touch-icon.png?50|}}]]
</code>
</webcode>

==== Icon ====

An [[docs:content:icon|icon]] can be used to get a compelling visual.
<webcode name="Default" frameborder=0>
<code dw>
[[https://combostrap.com|<icon name="logo.svg" width="96px" height="96px"/>]]
</code>
</webcode>


===== Styling =====

==== Attributes ====

An [[#internal|Internal]] or [[#email|email]] link can be styled with the [[docs:styling:styling|styling attributes]].

Example with the [[docs:styling:text-color#reset|reset color]] and [[docs:styling:underline|underline]].
<webcode name="Default" frameborder="0">
  * Input
<code dw>
<text color="#6c757d">
Colored text with a [[link?color=reset&underline=false#styling|styled link]]

Colored text with a [[link#styling|native link]]
</text>
</code>
  * Output
</webcode>

==== Stretchable ====
You can also stretch a link and make the whole parent clickable with the [[docs:styling:clickable|clickable styling attribute]].

==== Preview ====

By adding the ''preview'' attribute, you can create automatically a [[docs:content:tooltip|tooltip]] ''preview'' of the [[#internal|internal target page]] with:
  * the [[docs:page:name|page name]]
  * and the [[docs:page:description|description]]

{{:docs:content:combostrap_link_preview.jpg|}}

Live Demo:
<webcode>
  * With this markup:
<code dw>
Hovering on this link, you will see a [[?preview|preview of the actual page]]
</code>
  * You will get this output:
</webcode>

\\
\\

<note>
== AutoPreview ==


If you enable the [[#previewLink]] configuration, the ''preview'' attribute will be added on all internal links. 

In this case, you can disable the preview by setting the value to ''false'' (ie ''preview=false'').
</note>

==== Highlight Words in the target page ====

You can even create links that will highlight words in your target path.

Example:
<webcode name="Default" frameborder="0">
<code dw>
[[?s=Highlight&s=path#highlight_words_in_the_target_page|Click this link to highlight the words ''highlight'' and ''path'' on the target page]]
</code>
  * Output:
</webcode>

\\

<note important>
You can't use the form ''s[]'' to highlight words.  Why ? See [[#Square bracket not allowed]]
</note>

===== Wizard =====

To insert a link into your page, you can use the [[docs:utility:link_wizard]] in the editor.


===== Configuration =====

==== useDokuwikiLinkClassName ====
[[doku>|Dokuwiki]] sets class names (''wikilink1'',''wikilink2'',''urlextern'',...) on the link to differentiate them. Unfortunately, these class names have styling rules that are in conflict with [[:docs:theme:bootstrap|bootstrap]].

To resolve this issue, we have set other class names by link type that a web designer can use to style the links.

If you wish to get the DokuWiki class name on your links, you can get them by enabling the [[docs:app:configuration|useDokuwikiLinkClassName configuration]].


==== disableLink ====
If you don't want that ''Combostrap'' changes the default link behavior, you can disable it with the ''disableLink'' [[docs:app:configuration|configuration]].

Note that the link component enhances the [[doku>wiki:syntax#links|link]] syntax.
  * It allows any content inside. DokuWiki allows only text and media. If you disable it, you can't style your link or add any icon in it.
  * It allows advanced styling
  * It applies the [[:docs:theme:bootstrap|bootstrap styling by default]]

==== previewLink ====
If you enable this configuration, the [[#preview|preview]] attribute will be set on all internal link.





===== Support =====
==== I can't format the description to Italic ====

That's true, inside an link, this is actually not possible to use the %%//%% italic syntax.

This is to keep the compatibility with the old syntax that allows to have URL as a description. And an URL has the ''%%//%%'' italic syntax after the ''http'' scheme.

You can still create a link with an URL as description such as this one:
<webcode name="Default" frameborder="0">
  * Link with URL
<code dw>
[[https://combostrap.com|https://combostrap.com]]
</code>
  * Output:
</webcode>

==== Square Bracket Not allowed ====

The Closing Square Bracket '']'' is not allowed in a link.

For instance, this link format is not allowed
<code dw>
[[?s[]=word1+word2#fragment]]
</code>


Why ?
  * Because Dokuwiki does not accept any group in the regular expression pattern that capture the content of the link.
  * Hence, there is no way to create a logic that will capture all characters until the '']]'' or ''|'' character is found using a lazy regular expression.
  * Therefore, we use a greedy expression and the '']'' is denied to allow more than one link on a line.