Fork me on GitHub

Configuration & Callbacks


1. Rendering Type

The default output rendering is HTML. But SkrivMarkup is ready to manage other renderings.

At this time, you can use the DocBook output in addition to the HTML output.

// creation of the renderer object for DocBook output
$renderer = \Skriv\Markup\Renderer::factory('docbook');

2. Configuration

The SkrivMarkup renderer object accepts parameters to adapt its behaviour to your needs. These parameters are set in an associative array, given as parameter.

// configuration hash
$config = array(
    'anchorsPrefix'   => 'XYZ-',
    'footnotesPrefix' => 'ABC-'
);

// creation of the renderer object
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

3. Parameters

Name Type Default value Usage
shortenLongUrl boolean true Shorten long URLs when no title is given.
convertSmileys boolean true Convert smileys into special characters.
convertSymbols boolean true Convert symbols into special characters.
anchorsPrefix string null Prefix of anchor identifiers.
footnotesPrefix string skriv-notes-randomID- Prefix of footnote identifiers.
urlProcessFunction Closure null Function used to process URLs.
preParseFunction Closure null Function called to process the input text before parsing.
postParseFunction Closure null Function called to process the output text after parsing.
textToIdentifier Closure null Function called to transform a text in a usable identifier.
codeSyntaxHighlight boolean true Activate syntax highlighting in code blocks.
codeInlineStyles boolean false Activate inline styles for syntax highlighting.
codeLineNumbers boolean true Code lines must be numbered.
firstTitleLevel int 1 Offset of first level titles.
targetBlank boolean null A blank target must be added to every link.
nofollow boolean null All links must have the nofollow directive.
addFootnotes boolean false Add footnotes' content at the end of the page.
ext-lipsum boolean true Activate the <<<lipsum>>> extension.
ext-date boolean true Activate the <<date>> extension.

4. shortenLongUrl

With this parameter, you can disable URL shortening.

Example:

// configuration hash
$config = array(
    'shortenLongUrl' => false
);

// creation of the renderer object
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "[[http://www.site.com/very/very/very/long/long/url]]";
$html = $renderer->render($text);

Result:

<a href="http://www.site.com/very/very/very/long/long/url">
http://www.site.com/very/very/very/long/long/url</a>

instead of:

<a href="http://www.site.com/very/very/very/long/long/url">
http://www.site.com/very/very/very/long/...</a>

5. convertSmileys

With this parameter, you can disable smileys conversion.

Example:

// configuration hash
$config = array(
    'convertSmileys' => false
);

$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = ":-)";
$html = $renderer->render($text);

Result:

:-)

Instead of:

6. convertSymbols

With this parameter, you can disable symbols conversion.

Example:

// configuration hash
$config = array(
    'convertSymbols' => false
);

$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = ":triangle:";
$html = $renderer->render($text);

Result:

:triangle:

Instead of:

7. anchorsPrefix

Use it to define a prefix to anchors.

Example:

$config = array(
    'anchorsPrefix' => 'prefix-'
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "=Title=";
$html = $renderer->render($text);

Result:

<h1 id="prefix-Title">Title</h1>

instead of:

<h1 id="Title">Title</h1>

8. footnotesPrefix

Use it to define a prefix to footnotes.

Example:

$config = array(
    'footnotesPrefix' => 'foobar-'
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "text ((footnote))";
$html = $renderer->render($text);

Result:

<p>text <sup><a href="#foobar-1">1</a></sup></p>

instead of:

<p>text <sup><a href="#cite_note-1">1</a></sup></p>

9. urlProcessFunction

Add a processing function that will manage URLs.

This function must accept four parameters:

  1. the parsed URL;
  2. the label generated by the parser;
  3. a boolean, which set the default behaviour for blank targets:
    • null: outgoing links will be blank targeted;
    • false: no blank target on any link;
    • true: all links are blank targeted.
  4. a boolean, which set the default behaviour for the "nofollow" directive:
    • null: outgoing links are set as nofollow;
    • false: no one link should be set as nofollow;
    • true: every links should be set as nofollow.

The function must return an array with four elements:

  1. the generated URL;
  2. the generated label;
  3. a boolean, which set the blank targeting of this link:
    • null: use the default behaviour (see the targetBlank option);
    • false: no blank target on this link (override the default behaviour);
    • true: this links must be blank targeted (override the default behaviour).
    (without any clue, the safiest way is to return null)
  4. a boolean, which set the nofollow directive of this link:
    • null: use the default behaviour (see the nofollow option);
    • false: this link must not be set as nofollow (override the default behaviour);
    • true: this link must be set as nofollow (override the default behaviour).
    (without any clue, the safiest way is to return null)

The generated label will be used only if no title was given to the link.

Example:

$config = array(
    'urlProcessFunction' => function($url, $label, $targetBlank, $nofollow) {
        if ($url[0] !== '#')
            return array($url, $label);
        $id = substr($url, 1);
        $url = "/topic/$id";
        $label = "Topic num. $id";
        return (array($url, $label, null, null));
    }
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "Go to [[#123]] or [[this article|#456]]";
$html = $renderer->render($text);

Result:

<p>
    Go to <a href="/topic/123">Topic num. 123</a>
    or <a href="/topic/456">this article</a>
</p>

Instead of:

<p>
    Go to <a href="#123">#123</a>
    or <a href="#456">this article</a>
</p>

10. preParseFunction

Add a function that will be called before parsing. It could be useful to do some processings on context.

The function get the text that should be parsed as a parameter, and must return the text that will be parsed.

Example:

$config = array(
    'preParseFunction' => function($text) {
        $from = array('Mom', 'Dad');
        $to = array('Jane', 'Tarzan');
        return str_replace($from, $to, $text);
    }
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "{{family.jpg}}
Picture of Cheeta, Mom and Dad";
$html = $renderer->render($text);

Result:

<img src="family.jpg" />
<p>Picture of Cheeta, Jane and Tarzan</p>

Instead of:

<img src="family.jpg" />
<p>Picture of Cheeta, Mom and Dad</p>

11. postParseFunction

Add a function that will be called after rendering.

The function get the rendered text as a parameter, and must return the final text.

Example:

$config = array(
    'postParseFunction' => function($text) {
        $from = array('<ul>', '</ul>');
        $to = array('<ol>', '</ol>');
        return str_replace($from, $to, $text);
    }
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "* item 1
* item 2
* item 3";
$html = $renderer->render($text);

Result:

<ol>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
</ol>

Instead of:

<ul>
    <li>item 1</li>
    <li>item 2</li>
    <li>item 3</li>
</ul>

12. titleToIdFunction

Replace the function used to convert titles in DOM identifiers. The new function must accept two parameters:

  • The title's heading level.
  • The title string.

The function get the title as a parameter, and return the generated identifier. It will be called two times for each title; once for the title itself and again for ToC generation.

Example:

$config = array(
    'titleToIdFunction' => function($level, $text) {
        static $identifiers = array();

        if (isset($identifiers[$text]))
            return "title-$level-" . $identifiers[$text];
        $nextId = count($identifiers);
        $identifiers[$text] = $nextId;
        return "title-$level-$nextId";
    }
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "=Good=
==Water==
==Fruit Juice==
=Bad=
==Soda==
==Alcohol==";
$html = $renderer->render($text);

$toc = $renderer->getToc(true);

Result:

<h1 id="title-1-0">Good</h1>
<h2 id="title-2-1">Water</h2>
<h2 id="title-2-2">Fruit Juice</h2>
<h1 id="title-1-3">Bad</h1>
<h2 id="title-2-4">Soda</h2>
<h2 id="title-2-5">Alcohol</h2>

Raw table of contents:

Array(
    [0] => Array(
        [id] => title-1-0
        [value] => Good
        [sub] => Array(
            [0] => Array(
                [id] => title-2-1
                [value] => Water
            )
            [1] => Array(
                [id] => title-2-2
                [value] => Fruit Juice
            )
        )
    )
    [1] => Array(
        [id] => title-1-3
        [value] => Bad
        [sub] => Array(
            [0] => Array(
                [id] => title-2-4
                [value] => Soda
            )
            [1] => Array(
                [id] => title-2-5
                [value] => Alcohol
            )
        )
    )
)

13. codeSyntaxHighlight

This parameter could be used to disable syntax highlighting in code blocks. The functionality is activated by default. When disabled, code blocks are rendered as any other verbatim text blocks.

Note: SkrivMarkup syntax highlighting is done using the Generic Syntax Highlighter library. If it is not installed properly, SkrivMarkup will behave like if you disabled it explicitely.

Example:

$config = array(
    'codeSyntaxHighlight' => false
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = '[[[php
$a = 3;
]]]';
$html = $renderer->render($text);

Result:

<pre><code class="language-php">
$a = 3;
</code></pre>

instead of:

<pre class="language-php">
<ol>
<li class="li1">
<div class="de1">
<span class="re0">$a</span> <span class="sy0">=</span> <span class="nu0">3</span><span class="sy0">;</span>
</div>
</li>
</ol>
</pre>

14. codeInlineStyles

By default, the code syntax highlighting uses CSS classes to defines its graphical result. To make it easier to use, this option activate inline styles (inside the rendered source code).

Example:

$config = array(
    'codeInlineStyles' => true
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);
$text = '[[[php
$a = 3;
]]]';
$html = $renderer->render($text);

Result:

<pre class="language-php" style="font-family:monospace;">
<ol>
<li style="font-weight: normal; vertical-align:top;">
<div style="font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;">
<span style="color: #000088;">$a</span> <span style="color: #339933;">=</span> <span style="color: #cc66cc;">3</span><span style="color: #339933;">;</span>
</div>
</li>
</ol>
</pre>

instead of:

<pre class="language-php">
<ol>
<li class="li1">
<div class="de1">
<span class="re0">$a</span> <span class="sy0">=</span> <span class="nu0">3</span><span class="sy0">;</span>
</div>
</li>
</ol>
</pre>

15. codeLineNumbers

Use this parameter to disable line numbers in code blocks.

Example:

$config = array(
    'codeLineNumbers' => false
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = '[[[php
$a = 3;
]]]';
$html = $renderer->render($text);

Result:

<pre class="language-php">
<span class="re0">$a</span> <span class="sy0">=</span> <span class="nu0">3</span><span class="sy0">;</span>

instead of:

<pre class="language-php">
<ol>
<li class="li1">
<div class="de1">
<span class="re0">$a</span> <span class="sy0">=</span> <span class="nu0">3</span><span class="sy0">;</span>
</div>
</li>
</ol>
</pre>

16. firstTitleLevel

Defines the HTML heading of first level titles. It could be useful when your page has a separate title, which will be set as <h1>; then SkrivMarkup should render its first level titles as <h2>.

Example:

$config = array(
    'firstTitleLevel' => 2
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "= Analog
== Vinyl disc
== Audio cassette
= Digital
== Digital Audio Tape
== Compact Disc";
$html = $renderer->render($text);

Result:

<h2>Analog</h2>
<h3>Vinyl disc</h3>
<h3>Audio cassette</h3>
<h2>Digital</h2>
<h3>Digital Audio Tape</h3>
<h3>Compact Disc</h3>

instead of:

<h1>Analog</h1>
<h2>Vinyl disc</h2>
<h2>Audio cassette</h2>
<h1>Digital</h1>
<h2>Digital Audio Tape</h2>
<h2>Compact Disc</h2>

17. targetBlank

This parameter can be used to add a target="_blank" attribute onto every links. The behaviour depends of the parameter's value:

  • null (default): Blank targets are used for outgoing links (those containing "://" or starting with "//").
  • false: No blank target is used on any link.
  • true: Blank targets are used on every link.

Example:

$config = array(
    'targetBlank' => true
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "[[Ark | http://ark.skriv.org]]
[[Another page | ../page.html]]";
$html = $renderer->render($text);

Result:

<p><a href="http://ark.skriv.org" target="_blank" rel="nofollow">Ark</a>
<a href="../page.html" target="_blank">Another page</a></p>

instead of:

<p><a href="http://ark.skriv.org" target="_blank" rel="nofollow">Ark</a>
<a href="../page.html">Another page</a></p>

18. nofollow

This parameter can be used to add a rel="nofollow" attribute onto every links. The behaviour depends of the parameter's value:

  • null (default): The nofollow directive is set on outgoing links (those containing "://" or starting with "//").
  • false: The nofollow directive is not set on any link.
  • true: The nofollow directive is set on every links.

Example:

$config = array(
    'nofollow' => true
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "[[Ark | http://ark.skriv.org]]
[[Another page | ../page.html]]";
$html = $renderer->render($text);

Result:

<p><a href="http://ark.skriv.org" target="_blank" rel="nofollow">Ark</a>
<a href="../page.html" rel="nofollow">Another page</a></p>

instead of:

<p><a href="http://ark.skriv.org" target="_blank" rel="nofollow">Ark</a>
<a href="../page.html">Another page</a></p>

19. addFootnotes

By setting this parameter to true, you ask for the footnotes' HTML content to be added at the end of the page.

If you have defined a postParseFunction, it will be activated before the footnotes' addition.

Example:

$config = array(
    'addFootnotes' => true
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "Some text((some note))";
$html = $renderer->render($text);

Result:

<p>Some text<sup class="footnote-ref"><a href="#cite_note-1" name="cite_ref-1" id="cite_ref-1">1</a></sup></p>
<div class="footnotes">
    <p class="footnote"><a href="#cite_ref-1" name="cite_note-1" id="cite_note-1">1</a>. some note</p>
</div>

instead of:

<p>Some text<sup class="footnote-ref"><a href="#cite_note-1" name="cite_ref-1" id="cite_ref-1">1</a></sup></p>

20. ext-lipsum

By setting this parameter to false, you'll deactiviate the <<<lipsum>>> extension.

This extension is activated by default.

Example:

$config = array(
    'ext-lipsum' => false
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "<<<lipsum|2>>>";
$html = $renderer->render($text);

Result:

<p>&lt;&lt;&lt;lipsum|2&gt;&gt;&gt;</p>

instead of:

<p>Lorem ipsum vulputate purus a platea ut, vel fringilla non aliquet tempor viverra mauris, pharetra orci cursus nunc mi. Nam eget aliquam cras sapien venenatis magna, massa praesent consequat aenean molestie interdum ad, felis rhoncus ultricies auctor lectus. Taciti laoreet phasellus hac urna malesuada habitant, vestibulum hendrerit aenean condimentum sollicitudin sagittis dapibus, aliquam senectus ornare morbi ultrices. Dolor mollis vivamus egestas quam eros primis, velit imperdiet tortor pulvinar facilisis ante congue, inceptos libero quisque euismod scelerisque. Justo arcu mattis sit semper accumsan potenti proin curabitur lacinia cubilia, conubia augue convallis risus rutrum nec pretium fames. Torquent varius curae fusce suscipit tincidunt leo, class aptent vitae tellus nostra amet faucibus, maecenas fermentum ac litora nullam. Est neque dui.</p>
<p>Ultrices inceptos lectus eros vehicula tortor tellus platea luctus elit, scelerisque habitasse risus eu rhoncus nibh maecenas blandit, nulla ornare augue litora mattis aenean potenti tempor. Enim morbi rutrum proin dapibus placerat tincidunt sollicitudin dui dolor, etiam cras fusce per laoreet purus sodales commodo, amet primis convallis et tristique ac habitant consectetur. Nisl bibendum auctor aptent vel justo donec porttitor quisque nec metus ultricies eleifend sed, phasellus lacinia vitae etiam curabitur varius non porta vulputate mi id hendrerit. Est elementum neque nunc aliquam feugiat at fermentum aliquet himenaeos, volutpat vivamus nam ullamcorper venenatis imperdiet accumsan malesuada, semper odio a pharetra congue aliquam curabitur ante. Netus sociosqu suspendisse libero suscipit vestibulum, duis ut condimentum quis sem, velit faucibus sit pellentesque.</p>

21. ext-date

By setting this parameter to false, you'll deactivate the <<date>> extension.

This extension is activated by default.

Example:

$config = array(
    'ext-lipsum' => false
);
$renderer = \Skriv\Markup\Renderer::factory('html', $config);

$text = "<<date|%F|0>>";
$html = $renderer->render($text);

Result:

<p>&lt;&lt;date|%F|0&gt;&gt;</p>

instead of:

<p>1970-01-01</p>