Move markdown filter to PicoTwigExtension

lib/Pico.php

@@ -1109,6 +1109,9 @@ class Pico
     /**
      * Registers the twig template engine
      *
+     * This method also registers Picos core Twig filters `link` and `content`
+     * as well as Picos {@link PicoTwigExtension} Twig extension.
+     *
      * @see    Pico::getTwig()
      * @return void
      */
@@ -1119,22 +1122,13 @@ class Pico
         $this->twig->addExtension(new Twig_Extension_Debug());
         $this->twig->addExtension(new PicoTwigExtension($this));
 
-        $this->registerTwigFilter();
-    }
-
-    /**
-     * Registers Picos additional Twig filters
-     *
-     * @return void
-     */
-    protected function registerTwigFilter()
-    {
-        $pico = $this;
-
-        // link filter
+        // register link filter
         $this->twig->addFilter(new Twig_SimpleFilter('link', array($this, 'getPageUrl')));
 
-        // content filter
+        // register content filter
+        // we pass the $pages array by reference to prevent multiple parser runs for the same page
+        // this is the reason why we can't register this filter as part of PicoTwigExtension
+        $pico = $this;
         $pages = &$this->pages;
         $this->twig->addFilter(new Twig_SimpleFilter('content', function ($page) use ($pico, &$pages) {
             if (isset($pages[$page])) {
@@ -1147,15 +1141,6 @@ class Pico
             }
             return null;
         }));
-
-        // markdown filter
-        $this->twig->addFilter(new Twig_SimpleFilter('markdown', function ($markdown) use ($pico) {
-            if ($pico->getParsedown() === null) {
-                throw new LogicException("Unable to parse file contents: Parsedown instance wasn't registered yet");
-            }
-
-            return $pico->getParsedown()->text($markdown);
-        }));
     }
 
     /**

lib/PicoTwigExtension.php

@@ -59,11 +59,35 @@ class PicoTwigExtension extends Twig_Extension
     public function getFilters()
     {
         return array(
+            'markdown' => new Twig_SimpleFilter('markdown', array($this, 'markdownFilter')),
             'map' => new Twig_SimpleFilter('map', array($this, 'mapFilter')),
             'sort_by' => new Twig_SimpleFilter('sort_by', array($this, 'sortByFilter')),
         );
     }
 
+    /**
+     * Parses a markdown string to HTML
+     *
+     * This method is registered as the Twig `markdown` filter. You can use it
+     * to e.g. parse a meta variable (`{{ meta.description|markdown }}`).
+     * Don't use it to parse the contents of a page, use the `content` filter
+     * instead, what ensures the proper preparation of the contents.
+     *
+     * @param  string $markdown markdown to parse
+     * @return string           parsed HTML
+     */
+    public function markdownFilter($markdown)
+    {
+        if ($this->getPico()->getParsedown() === null) {
+            throw new LogicException(
+                'Unable to apply Twig "markdown" filter: '
+                . 'Parsedown instance wasn\'t registered yet'
+            );
+        }
+
+        return $this->getPico()->getParsedown()->text($markdown);
+    }
+
     /**
      * Returns a array with the values of the given key or key path
      *