It's better when it's simple

User Tools

Site Tools


Base Links Plugin

Compatible with DokuWiki


plugin Makes links beginning with "/" present as (always valid) internal links that point relative to your domain's root. Format is [[/pagename|optional title]]

Last updated on
Conflicts with

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Similar to externallink

Tagged with links

Author: Robert Meerman
Based on externallink by Otto Vainio

This plugin allows base-linking in DokuWiki. Links beginning with a “/” will link relative to the server's root, so [[/downloads/manual.pdf]] will link to just that: /downloads/manual.pdf, regardless of whether your installation of DokuWiki lies within a sub folder or not.

It improves a bit on externallink by allowing media titles: [[/downloads/manual.pdf|{{big_book.jpg}}]]


Same as normal links, except link must start with a “/” and use slashes through-out.


[[/downloads/manual.pdf|Educate yourself!]]

You can use [[:downloads:manual.pdf]] to explicitly use the normal DokuWiki link syntax.


Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.


Create the folder /lib/plugins/baselink and create syntax.php containing the following:


 * Plugin base links: Creates links relative to site root for all links beginning with "/"
 * @license    GPL 2 (
 * @author     Robert Meerman <>
 * @based_on   "externallink" plugin by Otto Vainio <>
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
class syntax_plugin_baselink extends DokuWiki_Syntax_Plugin {
     * return some info
    function getInfo(){
        return array(
            'author' => 'Robert Meerman, based on externallink plugin by Otto Vainio',
            'email'  => '',
            'date'   => '2007-05-19',
            'name'   => 'baselink',
            'desc'   => 'Makes links beginning with "/" present as (always valid) internal links that point relative to your domain\'s root. Format is [[/pagename|optional title]]',
            'url'    => '',
     * What kind of syntax are we?
    function getType(){
        return 'substition';
    // Just before build in links
    function getSort(){ return 299; }
    function connectTo($mode) {
		// \x2F = "/"
     * Handle the match
    function handle($match, $state, $pos, &$handler){
        $match = substr($match,2,-2); //strip [[ from start and ]] from end
        $match = explode("|",$match, 2);
        if( preg_match('/^\{\{[^\}]+\}\}$/',$match[1]) ){
			// If the title is an image, convert it to an array containing the image details
			$match[1] = Doku_Handler_Parse_Media($match[1]);
        return $match;
     * Create output
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            $text=$this->_baselink($renderer, $data[0], $data[1]);
            $renderer->doc .= $text;
            return true;
        return false;
    function _baselink(&$renderer, $url, $name = NULL) {
        global $conf;
        // Media in titles ( "{{...}}" ) are presented as arrays at this stage
			$name = $renderer->_getLinkTitle($name, $url, $isImage);
			// Quick Fix to supress naming bug ("[[/base/link|This & That]]" --displayed-as--> "This &amp; That")
			//$name = $renderer->_xmlEntities($renderer->_getLinkTitle($name, $url, $isImage));
			$name = $renderer->_getLinkTitle($name, $url, $isImage);
        $link['target'] = $conf['target']['wiki'];
        $link['style']  = '';
        $link['pre']    = '';
        $link['suf']    = '';
        $link['more']   = '';
        $link['class']  = $class;
        $link['url']    = $url;
        $link['name']   = $name;
        $link['title']  = $renderer->_xmlEntities($url);
        //output formatted
        return $renderer->_formatLink($link);

Change Log

  • 2006-03-06: Initial first release
  • 2006-04-19: _xmlEntities bugfix ([[/base/link|This & That]] was incorrectly rendered as “This &amp; That”)


Isn't this covered by the built-in syntax: [[this>someurl]]?

Completely handled all of my previous uses for baselink. Thanks!

Does this plugin completely supersede the externallink plugin?

In terms of functionality, yes. However the difference in syntax is significant enough for the two versions to exist side-by-side. Naturally I prefer the way baselinks works, I wrote it! (Based very heavily on externallink by Otto Vainio, really I changed almost nothing). — Robert Meerman 2006-04-19 02:04

I think, the use of _xmlEntities() is not necessary and in fact leads to problems.


[[/someurl|This & that]]

This will always render as: This &amp; that

Why? Well - when entering such text, special characters, like ampersand or “<” and “>” are already stored as “&amp;”, “&lt;” and so on. In fact all special characters are stored in a form, which never needs any conversion. A conversion may only be necessary, when editing the text files manually without DokuWiki - but who does this?

BTW: DokuWiki itself does it correct: A link like

[[somepage|This & that]]

will render correct as: This & that

Is there a fix for xmlEntities() ? I tried to remove those from the code but the example with the &amp; is still not working correctly.
I believe this has been fixed as of the 2006-04-19 release. — Robert Meerman 2006-04-19 02:00
Note that the JavaScript function “svchk()” no longer exists (and is now unnecessary) in DokuWiki, and does cause JavaScript errors, so references should be removed.
todd [at] rollerorgans [dot] com 2007-02-26
Fixed. — Robert Meerman 2007-05-19 16:45
Why is the code in _baselink() greatly simplified from the externallink plugin's _externallink() code? ie. the handling of when $name = NULL removed? — chris 2007-11-02 17:12

Fred 2008-01-23 23:32

Hi, is it possible to add a feature to change the target of the link ? Something like that :

[[/index.php>_top|Home]] to open the link in the _top frame?

Hi, The plugin only works “half” for me - what I mean is, if I add a PDF file and create a link to it as explained above in your instructions, the link in the wiki is green, but when I click on it I get a page not found error. Any suggestions to what I might be doing wrong? I made sure that the file is inside the wiki tree, it is along side other pages that show ok.

Remember DokuWiki only recognizes files in lowercase. A file named Manual.pdf will lead to this error you mentioned. Rename it to manual.pdf and everything will be fine. kabu

Hi, Thanks for the replay - however my PDF is all lower case…:-\ Any idea what else could cause this issue? Thanks!

Plugin doesn't work on Release 2012-10-13 “Adora Belle”
Url leads to Dokuwiki basedir, but not web server root dir

JoeT, 2015-11-21
Installed it on DokuWiki 2015-08-10 “Detritus” on two systems (Synology DSM [NAS] and a “DokuWiki on a Stick” version for Windows). On the Synology (Linux like system) the (https://) URL leads to the server root while on the Windows “stick” installation it leads to the DokuWiki home. Otherwise it does the job for url access to files.

biochemistrygmcs, 2021-11-08
Installation in Debain 11, with DokuWiki version 2018-04-22a “Greebo” gave warning regarding correct syntax for dokuwiki handler
Warning line:
function handle($match, $state, $pos, &$handler){
Changed to
function handle($match, $state, $pos, Doku_Handler $handler){
The warning disappeared.
Updated code is required to match latest DokuWiki version of 2021.

plugin/baselink.txt · Last modified: 2022-07-17 01:31 by 2003:c3:cf4b:b200:b506:33df:4a99:aa15

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki