Various small improvements

config/config.yml.template

@@ -3,7 +3,7 @@
 #
 site_title: Pico                    # The title of your website
 base_url: ~                         # Pico will try to guess its base URL, if this fails, override it here;
-                                    #     Example: http://example.com/pico/
+                                    #     Example: https://example.com/pico/
 rewrite_url: ~                      # A boolean (true or false) indicating whether URL rewriting is forced
 debug: ~                            # Set this to true to enable Pico's debug mode
 timezone: UTC                       # Your PHP installation might require you to manually specify a timezone
@@ -13,7 +13,7 @@ timezone: UTC                       # Your PHP installation might require you to
 #
 theme: default                      # The name of your custom theme
 theme_url: ~                        # Pico will try to guess the URL to the themes dir of your installation;
-                                    #     If this fails, override it here. Example: http://example.com/pico/themes/
+                                    #     If this fails, override it here. Example: https://example.com/pico/themes/
 theme_config:
     widescreen: false               # Default theme: Use more horicontal space (i.e. make the site container wider)
 twig_config:
@@ -27,11 +27,11 @@ twig_config:
 # Content
 #
 date_format: %D %T                  # Pico's default date format;
-                                    #     See http://php.net/manual/en/function.strftime.php for more info
+                                    #     See https://php.net/manual/en/function.strftime.php for more info
 pages_order_by_meta: author         # Sort pages by meta value "author" (set "pages_order_by" to "meta")
 pages_order_by: alpha               # Change how Pico sorts pages ("alpha" for alphabetical order, "date", or "meta")
 pages_order: asc                    # Sort pages in ascending ("asc") or descending ("desc") order
-content_dir: content/               # The path to Pico's content directory
+content_dir: ~                      # The path to Pico's content directory
 content_ext: .md                    # The file extension of your Markdown files
 content_config:
     extra: true                     # Use the Parsedown Extra parser to support extended markup;

lib/Pico.php

@@ -541,6 +541,8 @@ class Pico
      * @param string[] $pluginBlacklist class names of plugins not to load
      *
      * @return string[] installer names of the loaded plugins
+     *
+     * @throws RuntimeException thrown when a plugin couldn't be loaded
      */
     protected function loadComposerPlugins(array $pluginBlacklist = array())
     {
@@ -703,7 +705,7 @@ class Pico
      *
      * @return PicoPluginInterface instance of the loaded plugin
      *
-     * @throws RuntimeException thrown when a plugin couldn't be loaded
+     * @throws RuntimeException thrown when the plugin couldn't be loaded
      */
     public function loadPlugin($plugin)
     {
@@ -904,7 +906,7 @@ class Pico
         // merge default config
         $this->config += array(
             'site_title' => 'Pico',
-            'base_url' => '',
+            'base_url' => null,
             'rewrite_url' => null,
             'debug' => null,
             'timezone' => null,
@@ -912,6 +914,7 @@ class Pico
             'theme_url' => null,
             'twig_config' => null,
             'date_format' => '%D %T',
+            'pages_order_by_meta' => 'author',
             'pages_order_by' => 'alpha',
             'pages_order' => 'asc',
             'content_dir' => null,
@@ -1992,8 +1995,7 @@ class Pico
     /**
      * Returns the variables passed to the template
      *
-     * URLs and paths (namely `base_dir`, `base_url`, `theme_dir` and
+     * URLs and paths don't add a trailing slash for historic reasons.
-     * `theme_url`) don't add a trailing slash for historic reasons.
      *
      * @return array template variables
      */
@@ -2145,6 +2147,8 @@ class Pico
      *     "index", passing TRUE (default) will remove this path component
      *
      * @return string URL
+     *
+     * @throws InvalidArgumentException thrown when invalid arguments got passed
      */
     public function getPageUrl($page, $queryData = null, $dropIndex = true)
     {
@@ -2152,7 +2156,7 @@ class Pico
             $queryData = http_build_query($queryData, '', '&');
         } elseif (($queryData !== null) && !is_string($queryData)) {
             throw new InvalidArgumentException(
-                'Argument 2 passed to ' . get_called_class() . '::getPageUrl() must be of the type array or string, '
+                'Argument 2 passed to ' . __METHOD__ . ' must be of the type array or string, '
                 . (is_object($queryData) ? get_class($queryData) : gettype($queryData)) . ' given'
             );
         }
@@ -2465,15 +2469,15 @@ class Pico
     /**
      * Makes a relative path absolute to Pico's root dir
      *
-     * This method also guarantees a trailing slash.
-     *
      * @param string $path     relative or absolute path
      * @param string $basePath treat relative paths relative to the given path;
      *     defaults to Pico::$rootDir
+     * @param bool   $endSlash whether to add a trailing slash to the absolute
+     *     path or not (defaults to TRUE)
      *
      * @return string absolute path
      */
-    public function getAbsolutePath($path, $basePath = null)
+    public function getAbsolutePath($path, $basePath = null, $endSlash = true)
     {
         if ($basePath === null) {
             $basePath = $this->getRootDir();
@@ -2489,7 +2493,7 @@ class Pico
             }
         }
 
-        return rtrim($path, '/\\') . '/';
+        return rtrim($path, '/\\') . ($endSlash ? '/' : '');
     }
 
     /**