HTML Comment

This is a very simple plugin that allows HTML style comments to be used in the wikitext. They will show up unchanged in the XHTML output. They will not be rendered by the browser, but can be viewed with “View source code” command. The syntax is exactly like in HTML:

<!-- This is a HTML comment -->

This can be useful, if you're post-processing the HTML output in some way, e.g. to produce PDF documents. Some converters can use special HTML comments to steer the conversion process.

This plugin is based on the comment plugin by Esther Brunner.

Either save the PHP code below to the file lib/plugins/htmlcomment/syntax.php or use the plugin manager with the following URL:

Download: htmlcomment-plugin.zip

New in version 1.1:

• Incorporated changes made by Esther Brunner (see Discussion).
• Defined constant HTMLCOMMENT_SAFE to allow to switch back to old behaviour.
• Removed version number from plugin archive, since the plugin manager can't handle versioned archives.

<?php
/**
 * HTML Comment Plugin: allows HTML comments to be retained in the output
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Christopher Arndt <chris@chrisarndt.de>
 */
 
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
define('HTMLCOMMENT_SAFE', true);
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_htmlcomment extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Christopher Arndt',
            'email'  => 'chris@chrisarndt.de',
            'date'   => '2005-10-08',
            'name'   => 'HTML Comment Plugin',
            'desc'   => 'allows HTML comments to be retained in the output',
            'url'    => 'http://www.dokuwiki.org/plugin:html_comment',
        );
    }
 
    function getType() {
        return 'substition';
    }
 
    function getSort() {
        return 325;
    }
 
    function connectTo($mode) {
        $this->Lexer->addSpecialPattern("<\!--.*?-->", $mode,
          'plugin_htmlcomment');
    }
 
    function handle($match, $state, $pos, &$handler) {
        if ($state == DOKU_LEXER_SPECIAL) {
             // strip <!-- from start and --> from end
            $match = substr($match,4,-3);
            return array($state, $match);
        }
        return array();
    }
 
    function render($mode, &$renderer, $data) {
        if ($mode == 'xhtml') {
            list($state, $match) = $data;
            if ($state == DOKU_LEXER_SPECIAL) {
                $renderer->doc .= '<!--';
                if (HTMLCOMMENT_SAFE) {
                    $renderer->doc .= $renderer->_xmlEntities($match);
                } else {
                    $renderer->doc .= $match;
                }
                $renderer->doc .= '-->';
            }
            return true;
        }
        return false;
    }
}
 
?>

Please feel free to add comments, suggestions and questions here. Please sign them with your signature. — ChristopherArndt 2005-09-30 18:12

Hi Christopher, I've taken the liberty to fix a possible security issue. Before it was possible to include for example JavaScript in a HTML comment. Now XML Entities are escaped. If the old behaviour was what you intended for your plugin, restore the old version, but make clear it's a possible security risk. — Esther Brunner 2005-10-01 02:12

I had tested the following with the original version:

<!-- This is a HTML comment <script type="text/javascript"> window.alert('Gotcha!'); document.write("Vulnerable!");</script> -->

No dialog, no output. So the browser (Firefx) doesn't handle script tags inside HTML comments. Am I missing something here? Do other browser behave different? — ChristopherArndt 2005-10-01 03:24

Ok, I incorporated the changes into the distribution archive as well (see above). — ChristopherArndt 2005-10-09 00:07