Help pages using Markdown view renderer

This wiki article has not been tagged with a corresponding Yii version yet.
Help us improve the wiki by updating the version information.

This tutorial describes how to write your views for help pages using Markdown syntax to be able to generate PDFs from same source files.

View renderer

Create the file components/MdViewRenderer.php with following contents:

<?php
class MdViewRenderer extends CViewRenderer
{
    public $fileExtension='.md';

    protected function generateViewFile($sourceFile,$viewFile) {
        $md=new CMarkdown;
        $input = file_get_contents($sourceFile);
        $output = $md->transform($input);
        file_put_contents($viewFile,$output);
    }

}

Add it to the application config in config/main.php:

'components' => array(
        'viewRenderer' => array(
            'class'=>'MdViewRenderer',
        ),
        // .... other components config
    ),

Help pages

Create some help pages in the views/site/help directory as files with the .md extension. Your favourite text editor should enable syntax higlight in them.

Add a view action in your SiteController:

public function actions()
    {
        return array(
            'help'=>array(
                'class'=>'CViewAction',
                'basePath'=>'help',
            ),
            // .... other actions
        );
    }

Now just link the pages in your main menu:

'url' => array('/site/help', 'view'=>'sales'),

Generating PDF

Markdown files can be converted to PDF using pandoc, a swiss-army knife written in Haskell for converting documents between various formats. It calls Latex internally, so it must also be available on your system.

Assuming all images in the .md files start with /images we need to add a proper relative path for pandoc to find those files. So let's prepend ../../.. to them using sed:

TMPDIR=/tmp
for m in `ls *.md`; do
   sed 's/^!\[\(.*\)\](\(.*\))$/![\1](..\/..\/..\/..\2)/g' $m > ${TMPDIR}/$m;
done

Modified files are put into a temporary directory to avoid breaking them for HTML.

Generate a PDF using pandoc: ~~~ TMPDIR=/tmp pandoc -S -N -Vlang=polish --latex-engine=xelatex ${TMPDIR}/*.md -o test.pdf ~~~

Instead of using a wildcard (*) specify all files manually to force order in which pandoc concatenates them.

0 0
4 followers
Viewed: 5 705 times
Version: Unknown (update)
Category: Tutorials
Written by: nineinchnick
Last updated by: nineinchnick
Created on: Aug 9, 2013
Last updated: 4 years ago
Update Article

Revisions

View all history

Related Articles