Redesigned Customization page using Webpaint's Portfolio style.

Viewable here: Themes and Plugins

This PR is both for the page itself and for the portfolio framework that generates it.

Also note that it contains currently unmerged changes from #352 that are unrelated to this PR. Actual changes begin at Implemented Portfolio and Revamped Customization. https://github.com/picocms/Pico/pull/358/commits/8819d4379aea0814e1bae513660cc65abdba0bb3

Previously discussed in #352.

Areas to improve on:

• [x] Customizable "Launch Site" Button Text.
  • [x] What should the text be on customization? Download? Launch Site? View on GitHub? (since I think all but NotePaper go to GitHub).
• [x] Better utilization of Meta text in existing tiles...
• [x] Separate Plugins and Themes
• [x] Improve Javascript on portfolio-detail-view.
• [x] Multiple categories for themes/plugins - Started, but always room for improvements / more
  • For Themes: Single-page, Static Website, Blog-Style, etc.
  • For Plugins: Blogging, Social, Developer, etc
• [x] Better representation of Plugins (especially when too abstract for a screenshot)
  • [x] Possible Style: "muted", gray puzzle piece background with persistent overlay text, but only turns green on hover.
  • [x] Initial Styles and Effect
  • [x] Better Puzzle Piece graphic.
• [x] Use Jekyll "Collections" to separate each theme and plugin into its own file.
  • [x] Migrate Heading and Description to content
    • [x] ~~Migrate Heading~~
      • Markdownified Heading instead, since it's not contiguous with the Description.
      • Also, it's used for the Overlay, so it needs to be in an isolated variable for that.
    • [x] Migrate Description
  • [x] Provide backwards compatibility with YAML method for non-collection based portfolio pages.
  • [x] Provide a blank YAML template that contributors can fill out to easily add their content.
    • [x] Include submission guidelines / readme with things like screenshot resolution and location.
    • [x] Fork and PR instructions? ~~This is probably out-of-scope.~~ As Links.
  • [x] Move images into collection
    • [x] Remove "Theme" from the names of theme screenshots, as it's redundant now.
    • ~~Remove "Default Theme" images. Maybe re-purpose them elsewhere.~~
    • ~~Use these images for the About Page, instead of its own.~~
• [x] a tags in the info section should be white, not green.
• ~~Captions for carousel items?~~ Probably not worth the effort, since we already have a content area.
• [x] Escape all variables that are vulnerable to apostrophes.
• ~~Provide "Documentation" on how to use gallery and portfolio.~~ "Unnecessary"
  • ~~Don't forget about things like info._blank, page.portfolio.categories, include categories=variable and other examples that may not be represented on the current page.~~
• [x] Fix whitespace on either side of : in the Item-Details <span>.
• [x] Customize or slow carousel.
  • [x] Slowed
• [x] Second, text-focused, pop-up content area for Plugins page.
• [x] Fix odd cut-off on right edge.
• [x] Update About page URLs ~~(and image locations)~~
• [x] Add styles for portfolio-detail-view code
• [x] Better implementation of ~~plugin~~ defaultThumbnail styles trigger
• [x] Merge new styles with regular styles.
• [x] Correct image paths (and any others) with {{ site.github.url }}. Remove leading / from paths.
• [x] Change myCarousel ID to entry-{{ forloop.index0 }}-carousel or something similar.
• [x] Check commented JS from https://github.com/picocms/Pico/pull/358/commits/e3cd95b4fe3a30d8a3aa82c8db9c38d9d53843fa
• [x] Use the "active item" class to make active item stay lit.
• [x] Don't break the styles for "standalone" overlay images
• [x] Make sure that the bg color transitions are located in the right CSS file (pico.css) for consistency with other styles.
• [x] IE8 Compatible Styles (https://github.com/picocms/Pico/pull/358#issuecomment-247850979)
• [x] Change meta to description
• [x] New blank info lines implementation.
• ~~Find a replacement for the None category? (created when I removed multi-page)~~
• [x] Create Theme/Code image for "Plus" tile.
• [x] Bigger plugin content (excerpts or whole readme's)
• [x] Standardize Description (meta) punctuation.
• [x] Set "Contribute" tile layout.
• [x] Change name of layout variable.
• [x] Image/List Layout Problem (Card View)
• [x] Contribute Tile Text
• [x] Getting Started Section
• [x] Revise Docs Contribute section
• [x] Recreate defaultThumbnail Images as SVG
• [x] Create Plugin-Specific Contribute Tile
• [ ] Clean and Upload Source Files
• [x] Replace Default Theme images with high-res plugin graphic

• Investigate odd YAML behavior that is treating my categories as an array instead of a string. For now, I'm treating this variable as an array (and maybe converting the syntax) since it probably should be an array. It was just confusing because I was expecting a string of HTML ID's separated by spaces. For comparison, description is correctly treated as a string (otherwise it'd be a spaceless jumble of letters).

description: Google Analytics for Pico with basic options.<br><br>This plugin will automatically add the Google Analytics tracking script to the < head > section of each page generated by Pico.
categories: plugin developer. Why is this an array and not a string?

Is creating:

description: "Google Analytics for Pico with basic options.<br><br>This plugin will automatically add the Google Analytics tracking script to the < head > section of each page generated by Pico."
categories: ["plugin","developer.","Why","is","this","an","array","and","not","a","string?"]

Reissuing this PR since @PhrozenByte goofed. :wink:

View the current page at: http://smcdougall.github.io/Pico/about/

Old Discussion at: #349

• [x] Remove "Expert Webmaster".
  • [x] Keep "But what does that even mean"?
• [x] Bottleneck on large sites, Overkill on small sites.
• [x] Workflow gallery should tell a story.
  • [x] Add index.twig and DummyPlugin.php screenshots.
• [x] Use theme images from #358.
• [x] Link to Markdown basics and syntax.
• [x] For Markdown example, use actual content, italics, bold, links, images, lists, and headings.
• [x] Dashes for dates.
• [x] Actual content for YAML to match Markdown.
  • [x] Revise Content
  • Remember to reuse this example for a tutorial later on.
• [x] Associative array of social links and multi-line description examples for YAML.
  • [x] Add social buttons to content-sample.
    • See bf1663cc1c6f31626c7274c3221411c7956f703f
    • Add this idea to the cookbook. (Or at least make a proper note for later).
• [x] Add a line about "stupidly simple" applying to Pico's code base as well (customization section, see #355).
• [x] Remove "Themes" quotes.
• [x] Remove "Theme" from all themes and file names, same as planned for #358.
• [x] Add more themes, like Identity and Clean Blog.
  • [x] Remove Simple Sidebar.
• [x] Expand Plugin Section with Details.
• [x] Add a note (or more) about Pico being Open Source and MIT licensed!
• [x] "Blazing fast" should be mentioned in the "not a turn-key" section.
• [x] Add a line about overcomplicated CMS interfaces.
• [x] Restore accidentally removed CSS chunk.
• [x] Remove redundant image versions.
• [x] Compare and merge Fancybox styles with original styles.

The phpDocumentor folder of the gh-pages branch (introduced with Pico 1.0 resp. #260) should be automatically generated when both a release is published (create a distinct phpDocumentor folder for any minor release - see http://semver.org/) and someone commits to the master branch.

By the way, our ToDo list for the final 1.0.0 release:

• [x] Add "Build & Release process" to CONTRIBUTING.md, added in bef1502
• [x] Automatically generate phpDoc, added in bef1502
• [x] Website: Add "What's new" to upgrade.md, added in #276
• [x] Add a README.md for the gh-pages branch, added in https://github.com/picocms/Pico/commit/66bcb181cc82d760573a00d2bf472e4c7fb900c9
  • Don't forget to link to http://themes.iki-bir.com/webpaint/multipage/full/
• [x] Remove the Pico 0.X Plugins section from website with the final release of Pico 1.0.0
• [x] Update Pico Wiki
• [x] Wait for more feedback :smile:

Deferred:

• ~~New default theme using Bootstrap 3 or (provided it has been released already) Bootstrap 4~~
• ~~Website: Overhaul _development/ collection resp. development.md~~
• ~~Website: Improve _cookbook/ collection resp. cookbook.html~~
  • ~~Decide where to put links to it (inline user docs? website user docs? website dev docs?) and actually create the links~~

Pico's Nginx documentation is practically non-existent. It should be improved and provide some detailed examples equivalent to what is provided for Apache in .htaccess.

A discussion has already begun on https://github.com/picocms/Pico/commit/d8f916691809b19b05104906ee3700c5cf3f8407. It seems there is a lot to consider when using a Regex Location Block for Pico's rewriting, as Nginx will only use the first matching rule it finds. Since a typical Nginx setup also uses Regex to detect when to send a page to PHP, a misconfiguration can easily break PHP detection altogether.

The solution seems to be placing the PHP Location Block above any Pico rewrite blocks, that way any requests to index.php get properly matched.

In the current example, location ~ ^/pico(.*) matches both the Page ID you're trying to rewrite (eg /pico/page) and also the index itself (at /pico/index.php, resolved from the URI /pico/?page).

Since /pico/index.php matches location ~ ^/pico(.*), Nginx has succeeded in finding a match and will not move on to match it to location ~ \.php$. The PHP page gets served as a download file instead of interpreted by PHP.

At the moment this PR is "the mother of WORK IN PROGRESS"... :smile:

Actually I don't have much to show yet, I'm primarily trying to point to PhrozenByte/pico-admin. I decided to start with development of the admin plugin, because it may give us some more ideas for Pico ~~1.1~~ 2.0 (renamed 2016-12-12). Please use this PR to give feedback about the plugin (otherwise the discussion may get a bit fragmented).

@theshka: Do you think it makes sense to ask @picocms once again to convert his/her account to an GitHub Organization? This will allow us to use picocms/pico-admin instead... This is particularly meaningful when bearing in mind that I'm planning to create multiple repositories (picocms/pico-composer, picocms/pico-pagination, picocms/pico-tags, picocms/pico-feeds, picocms/pico-i18n, picocms/pico-search)...

Most importantly we have to make a decision about replacing Pico's default theme (see #297) with Pico 2.0 or to defer this until Pico 3.0. What are your opinions about this? (especially, but not solely, @theshka) My objections are primarily related to BC, but I have not formed a opinion about this yet. Please also refer to the "Decisions to make" section below.

Refer to http://picocms.org/phpDoc/pico-1.1/ for updated phpDoc class docs.

Plannings for the more distant future (i.e. Pico 3.0) can be found in #317. ~~At the moment it's planned to let Pico 3.0 follow Pico 2.0 (i.e. no Pico 2.1).~~

As always, feedback is highly appreciated!

#edit: This release has been renamed to Pico 2.0 (previously Pico 1.1) on 2016-12-12, however we can't rename the branch, thus development will still happen on the pico-1.1 branch.

Planned changes to Pico's core

• [x] Add Pico::VERSION constant
• [x] Add includePico() function to prevent access to $this/Pico object in config/plugin files (use composer's includeFile() function instead?)
• [x] #330: Implement a modular config
  • [x] Instead of using *.config.php files, use *.yml files to configure Pico. YAML is much easier to understand, more user friendly and (at least a bit) more error-tolerant, but still very powerful. Don't break BC by letting PicoDeprecated still read config/config.php.
• [x] Allow Markdown configuration (Parsedown doesn't support much configuration, probably it will be limited to the optional usage of Parsedown instead of ParsedownExtra, Parsedown::setBreaksEnabled(), Parsedown::setMarkupEscaped() and Parsedown::setUrlsLinked())
• [x] Create a (de facto never updated) pico-composer project to allow composer users to install Pico as dependency and benefit from composer's update mechanism; see @gilbitron's BaunCMS/Baun repo
  • ~~Think about how users can easily install plugins with dependencies when they aren't using composer, but a pre-bundled release~~
• [x] #299: Integrated 404 Not Found page
• [x] Add Pico::is404Content() method returning true when Pico::$requestFile doesn't exist (i.e. on404ContenLoading has been triggered)
• [x] Remove PicoParsePagesContent
• [x] Remove PicoExcerpt
• [x] Don't sort pages when a unknown $config['pages_order_by'] is specified -- breaks BC
• [x] Trigger the onMetaHeaders event only once, cache results of Pico::getMetaHeaders().
• [x] Update README.md to use a screenshot hosted on our website
• [x] Let users sort pages by arbitrary meta values (like Pico's sort_by Twig filter)
• Overhaul Pico::parseFileMeta(). Preserve BC with PicoDeprecated.
  • [x] Don't lower unregistered meta headers on the first level unsolicited (e.g. SomeNotRegisteredKey: foobar in the YAML Frontmatter should result in $meta['SomeNotRegisteredKey'], not $meta['somenotregisteredkey']).
  • [x] Don't compare registered meta headers case insensitive, rather allow registering multiple meta headers to result in the same meta value by flipping Pico::$metaHeaders
  • [x] Let users explicitly set the formatted date in the YAML Frontmatter (e.g. date_formatted: Friday, 1st of December, 2000)
• [x] Add a tree structure for all known pages

Planned changes to Pico's plugin system

• [x] Allow Pico plugins to trigger custom events
• [x] Add onSinglePageLoading event (new preliminary event to onSinglePageLoaded)
• [x] When changing the $page parameter of the onSinglePageLoaded event to null, don't add this page to $pages (keeping $page['sub/page'] = null makes no sense, thus no BC break)
• [x] Add plugin API versioning (new DummyPlugin::API_VERSION constant with Pico's major.minor version describing which API version the plugin expects; if the constant doesn't exist, assume 1.0); this allows us to overhaul the plugin event system in the future without breaking BC
  • [x] #318: Add onParsedownRegistered event and pass $parsedown (instance of Parsedown) to allow extending erusev/parsedown
  • [x] Replace onTwigRegistration event with onTwigRegistered and pass $twig (instance of Twig_Environment), remove $twig parameter from onPageRendering event
• [x] Let PicoDeprecate differentiate between legacy levels (i.e. always enable the plugin to e.g. read config.php in Pico's root dir, but trigger deprecated events only when plugins of a specific legacy level are present)
• [x] Allow to manually load plugins (i.e. add Pico::loadPlugin() method)
• [x] Allow Pico plugins to be installed through composer.json
• ~~Support multiple plugin dirs~~
• ~~Add hook/event for Pico::getPageUrl()~~
• [x] Add more events to Pico::readPages(), similar to the events of the current page
• [x] Order plugins (execution order matters!) by evaluating their dependencies. Older plugins implicitly depend on PicoDeprecated. See tsort, marcj/topsort.php, haberco/topological-sort-php.
• [x] Add a event between onPagesLoading and onPagesLoaded passing the unsorted pages array (e.g. onPagesDiscovered).
  • Also remove the $currentPage, $nextPage and $previousPage parameters from the onPagesLoaded event, fire a separate event to "publish" them
• [x] Load plugins from plugins/<plugin name>.php (non-recursive) and plugins/<plugin name>/<plugin name>.php (the class file must be named after the directory) only. Plugins with multiple classes may need to register an autoloader on their own. Also see #203 -- breaks BC

Planned changes to Pico's UI (themes, Twig, routing, …)

• [x] #347: Drop the "index" part of URLs
• ~~Support multiple theme dirs~~
• [x] Make theme_url configurable; the default value should support that Pico::$themesDir is a arbitrary deep sub path of dirname($_SERVER['SCRIPT_FILENAME']) (i.e. index.php resp. httpdocs folder); otherwise fallback to ~~themes (and not~~ basename(Pico::$themesDir)~~)~~
• ~~Use Twig blocks in default theme (i.e. {% block replace_or_extend_me %}...{% endblock %})~~
• [x] #305: Allow access to query string in Twig templates (i.e. $_GET superglobal)
• [x] Support REQUEST_URI-based URL rewriting to allow a much simpler webserver configuration
• [x] Use flexbox in Pico's default theme to pin the footer to the bottom of the window
• [x] Drop ~~{{ site_title }} and~~ {{ rewrite_url }} in favour of ~~their~~ its {{ config.* }} equivalent~~s~~. ~~Rename {{ current_page }} to {{ page }}.~~ Drop {{ is_front_page }} (use {% if page.id == "index" %} instead). Preserve BC with PicoDeprecated.
• [x] Calculate the previous and next page for all pages (doesn't increase calculation time, array_search() in Pico::discoverCurrentPage() walks through all pages anyway). ~~Drop {{ next_page }} and {{ previous_page }} in favor of their resulting {{ page.* }} equivalents (see above). Preserve BC with PicoDeprecated.~~
• [x] Add only pages of the first level to the page navigation by default (e.g. page.md and sub/index.md, but not sub/page.md) -- breaks BC (more or less...)
• [x] Ignore all pages starting with a _ for the page navigation by default (e.g. _meta.md and all files in _collection/ are skipped) -- breaks BC (more or less...)

Website & Documentation

See picocms/picocms.github.io#18

• [x] Add Bountysource (merge enhancement/bountysource branch)

New official plugins/themes

The following plugins won't defer the release of Pico 2.0:

• Blog features
  • ☐ Pagination
  • ☐ Tags
  • ☐ RSS Feeds
  • ☑ #365: File Prefixes
• ☑ Robots (serve a robots.txt and sitemap.xml)
• ☐ Contact form
• ☐ https://github.com/picocms/Pico/issues/376#issuecomment-265972068: Excerpts
• ☐ #297: Bootstrap 4 theme
• ☐ Editor/Page Admin

First of all: Why? The sourcecode of existing forks like BaunCMS and PhilleCMS isn't "stupidly simple" anymore... You can read Picos sourcecode from top to down and even copy&paste programmers will understand what's going on. It's all about "understanding at first glance".

Most important second: All changes are 100% backward compatible.

I considered writing something own, but then caught up with Pico. The only thing missing was clean code - Picos concept, workflow and code really is "stupidly simple", but very powerful. Actually I just did a code refactoring. I don't want to fork Pico and I won't do it even if you reject my changes (obviously I'll still use it myself :smile:).

This should be v1.0 ready. I recommend to release it as v1.0-beta, waiting some weeks to test it on a large user basis (I'll fix all appearing problems) and finally releasing it as Pico 1.0 :smile:

Please give me a hint if you'll merge this, I'll then update the homepage (gh-pages branch), changelog.txt etc. accordingly.

What did I do?

• Fixes #79, Closes #93, Fixes #99, Closes #103, Closes #116, Fixes #140, Fixes #158, Closes #171, Fixes #210, Closes #241, Closes #244, Closes #246, Fixes #248, Fixes #249, Fixes #250, Fixes #251, Fixes #253, Fixes #257, Fixes #267
• The code is now documented, code styling follows PSR. Pico superficially grows from 400 LoC to 1000 LoC, when removing all comments, Pico grows from 300 LoC to 500 LoC, mostly because of new public getter and helper methods (= 100 LoC) and PSR code styling. As said, there are no big functional changes, it's more a code refactoring.
• The new routing system now works out-of-the-box (even without rewriting) with any webserver using the QUERY_STRING routing method. Internal links now look like ?sub/page, rewriting to basically remove the ? is still possible and recommended. Contrary to Pico 0.9 every webserver should work just fine. Pico 0.9 required working URL rewriting, so if you want to use old plugins/themes/contents, a working rewrite setup may still be required. If you're not using the default .htaccess, you must update your rewrite rules to follow the new principles. Internal links in content files are declared with %base_url%?sub/page. Internal links in templates should be declared using the new link filter (e.g. {{ "sub/page"|link }}), what basically calls Pico::getPageUrl(). You musn't change anything if you setup rewriting (what was required in Pico 0.9...), so I assume this to be fully backward compatible :smile:
• I've implemented a whole new plugin system while maintaining full backward compatibility. See the class docs of IPicoPlugin for details. The new event system supports plugin dependencies as well as some new events. It was necessary to reliably distinct between old and new events, so all events were renamed. The new PicoDeprecated plugin is crucial for backward compatibility, it's enabled on demand. Refer to its class docs for details.
• I completely overhauled the sorting algorithms, so sorting by date now works as expected by using timestamps and index files are listed before their sub pages (so e.g. sub/index.md is listed before sub/foo.md).
• Inaccessible files (like sub.md while sub/index.md exists) are now excluded from the pages list.
• Now supporting per-directory 404.md files (if there is a sub/404.md, this file is displayed in favour of the global 404.md file, when e.g. the non-existing sub/notexisting.md is requested)
• The file extension of content files is now configurable.
• Heads up! #158 is fixed only when the PicoParsePagesContent plugin isn't enabled. It's disabled by default, but gets automatically enabled with PicoDeprecated as soon as an old plugin is loaded. This is necessary to maintain backward compatibility. You can still disable it manually by executing $pico->getPlugin('PicoParsePagesContent')->setEnabled(false); or adding $config['PicoParsePagesContent.enabled'] = false; to your config.php.
• The meta headers are now parsed by the YAML component of the Symfony project (see #116) and it isn't necessary to register new headers during the onMetaHeaders event anymore. The implicit availability of headers is supposed to be used by users and pure (!) theme developers only, so we're still instructing plugin developers to register their headers. See the commit message of 7537159 for more detail.
• Meta header variables are now accessible in content files using %meta.*%, so you mustn't repeat yourself. You can now put an excerpt into the description meta variable and output the same content at the beginning of the article using %meta.description% (see index.md for a example).
• Initialization of Pico now works completely different: rather than defining constants (which are probably conflicting with other applications...), Pico now expects its paths to be passed as parameters to the constructor. The constructor doesn't start Picos processing anymore, you now have to call the Pico::run() method, which returns the parsed page contents instead of directly echoing them. The PicoDeprecated plugin defines the now deprecated constants ROOT_DIR, LIB_DIR etc., so old plugins can still use them. Those constants are defined before reading config.php in Picos root folder, so upgrading users usually aren't bothered with e.g. a PHP Notice: Use of undefined constant ROOT_DIR - assumed 'ROOT_DIR' error when using ROOT_DIR in their config.php (so: no BC break). New users don't need the constants anymore, relative paths are now always interpreted to be relative to Picos root dir, so $config['content_dir'] = 'content'; is always sufficient (previously this was depending on the webserver config). All these changes are supposed to improve Picos interoperability with other applications and allows developers to integrate Pico in other applications, therefore I additionally added a new Pico::setConfig() method to even make the use of a config.php optional.
• The Twig cache dir doesn't exist anymore. The provided directory never was helpful, in most cases one still had to make the directory writable for the webserver, so it never worked out-of-the-box.
• All index.html files were removed; instead of helping users to secure their website, they create a false sense of security. This leads to situations like "I'm receiving a empty website when navigating to the content folder, thus everything must be safe!"
• I decided explicitly to NOT implement pages as objects ("stupidly simple", see above). Anyway, I think plugin developers shouldn't manipulate data in "wrong" events, this could lead us to unexpected behaviour. Sure, plugin developers still can do this, we're passing variables by reference, but it's not that obvious. I even thought about dereferencing the values after the corrosponding event was called, but that would be backward incompatible. What do you think?
• How to fix the "composer problem" discussed in #221 and #223? There's a very simple solution: When creating a release on GitHub (after you've pushed the tag) you can upload "binaries". Simply execute composer locally, create a ZIP archive and upload the result as "binary".
• I didn't care much about #110, #238, #239 and #240 because I simply don't need these features. But I think they are good ideas and the core should support this. Just my 2 cents :smile:
• #201 and #231 should be closed - this can easily be achieved with plugins. In fact, there are already plugins adding support for these features...
• Imo distinct documentations for users, theme designers and plugin devs is MUCH more important than unit tests... Pico is a project with just about 500 LoC (+ comments), such a manageable project doesn't necessarily require unit tests - they are nice to have, but that's it. Documentation should be the top priority!
• Note: I'm no english native speaker. Maybe someone should look through my code comments :smile:

Work in progress for an About/Overview type page. Something users can read to learn what Pico is before moving on to the Docs (which begin with "Install" instructions).

http://smcdougall.github.io/Pico/about/

Currently, any notes I have are inline. Any bulleted items are notes. I'll remove them as I fill out the page more.

Rough draft is complete. Still needs further revision and editing, but I wanted to share what I've gotten done so far.

View-able at http://smcdougall.github.io/Pico/nginx/

Any input is appreciated. :smiley:

After 21 months and 157 commits, we're happy to announce the release of the first beta of Pico's second major release! 🎉

Click here to download Pico v2.0.0-beta.1: pico-release-v2.0.0-beta.1.tar.gz

Pico 2.0 introduces some major new features, but unfortunately also comes with some BC-breaking changes. However, as always, we tried to maintain BC whenever possible using Pico's official PicoDeprecated plugin. If you've spared to use features, that are deprecated since Pico 1.0, you should be fine. Since we wanted to finally release the first beta, we unfortunately didn't have time to write a changelog or upgrade instructions yet. We'll publish them with the second beta. Nevertheless, the upgrade process should be pretty straight-forward and is basically the same as with Pico 1.0.

Even though the changes are pretty immense, we are aware of the fact that developing Pico 2.0 took a pretty long time. In the future we'll try to release Pico more often and in smaller pieces.

For a complete list of changes, please refer to Pico 2.0's main pull request #334. You can find Pico 2.0's source code in the pico-1.1 branch. Please note that you can now find both Pico's official PicoDeprecated plugin and Pico's official default theme in separate repos.

As always, feedback is highly appreciated! ❤️

If you've come here for support, I suggest you take a look at the history of how effective that is likely to be. Just go down the list and see how many responses you find, and make your assumptions on how likely your problem is to get solved here accordingly.

In my case, I even went so far as to contact the dev directly, and was summarily rebuffed and told this was the place... which it clearly isn't.

Pico, I have to suggest, is dead. Indeed, I now rather suspect it was an ego thing the dev did to see how many links and how much ranking he could get. Disappointing, really... this could have been a killer app.

This is a long-live issue to track and discuss wished updates of our website resp. documentation.

Website

• [x] Add GitHub, Twitter and IRC icon to website
• [x] Add current version number to Download page
• [ ] Overhaul and extend _development/ collection resp. development.md
• [ ] Improve _cookbook/ collection resp. cookbook.html
  • Decide where to put links to it (inline user docs? website user docs? website dev docs?) and actually create the links
• [x] #358: Use Webpaint portfolio ("Showcase") to re-implement customization.md with extended information about and screenshots of all plugins and themes
  • Use distinct data files (_data/plugins.md and _data/themes.md) to make adding plugins/themes much easier
  • See phpDoc.html and _data/phpDoc.md as a reference
• [ ] Look through the wiki to include more plugins and themes on Pico's website
• [ ] Decide where to put large source files, see https://github.com/picocms/Pico/pull/358#issuecomment-257721007 and following
• [x] Add a sane way to add "Read more..." pages (e.g. upgrade.md or nginx.md (#343))
• [x] #309: Add a phpDoc overview page
• [x] #345: Add extended nginx documentation
• [x] #349 + #352: Add "About Us" page
• [ ] #368: Create a "advanced asset handling" howto (allow access to certain files (matched by MIME type) in the content/ folder)
• Decision to make: Replace <h2> headers with a floating box in the TOC-reserved space on the left, see https://github.com/picocms/Pico/pull/349#issuecomment-220638496 for an example

Documentation

• [x] Add IRC to the "Getting Help" section
• [x] Add the "What information do we need" paragraph of the Issues section of our CONTRIBUTING.md to the "Getting Help" section
• [ ] Explain how to use Pico with composer require picocms/Pico and provide a appropriate index.php
  • Maybe create a distinct pico-composer project instead? See #317
• [ ] Pico 1.1: Update nginx rewrite rules in user docs/nginx details page

According to the Twig documentation, this example should display "Bob Smith, Alice Dupond":

{% set people = [
    {first: "Bob", last: "Smith"},
    {first: "Alice", last: "Dupond"},
] %}

{{ people|map(p => "#{p.first} #{p.last}")|join(', ') }}

However, it throws the following error:

[Sun Mar 20 23:32:27.248660 2022] [php:error] [pid 12] [client 172.17.0.1:64928] PHP Fatal error:  Uncaught TypeError: Illegal offset type in isset or empty in /var/www/localhost/htdocs/pico/vendor/picocms/pico/lib/PicoTwigExtension.php:285
Stack trace:
#0 /var/www/localhost/htdocs/pico/vendor/picocms/pico/lib/PicoTwigExtension.php(152): PicoTwigExtension::getKeyOfVar()
#1 /var/www/localhost/htdocs/pico/vendor/twig/twig/src/Environment.php(497) : eval()'d code(40): PicoTwigExtension->mapFilter()
#2 /var/www/localhost/htdocs/pico/vendor/twig/twig/src/Template.php(453): __TwigTemplate_5751ea7c50eca1750bc3952b6ce22d8d4c2142ae3b68d7ee69add82bb55ba61d->doDisplay()
#3 /var/www/localhost/htdocs/pico/vendor/twig/twig/src/Template.php(420): Twig\\Template->displayWithErrorHandling()
#4 /var/www/localhost/htdocs/pico/vendor/twig/twig/src/Template.php(432): Twig\\Template->display()
#5 /var/www/localhost/htdocs/pico/vendor/twig/twig/src/TemplateWrapper.php(47): Twig\\Template->render()
#6 /var/www/localhost/htdocs/pico/vendor/twig/twig/src/Environment.php(384): Twig\\TemplateWrapper->render()
#7 /var/www/localhost/htdocs/pico/vendor/picocms/pico/lib/Pico.php(514): Twig\\Environment->render()
#8 /var/www/localhost/htdocs/pico/index.php(33): Pico->run()
#9 {main}
  thrown in /var/www/localhost/htdocs/pico/vendor/picocms/pico/lib/PicoTwigExtension.php on line 285

The second example doesn't throw an error:

{% set people = {
    "Bob": "Smith",
    "Alice": "Dupond",
} %}

{{ people|map((last, first) => "#{first} #{last}")|join(', ') }}

However, instead of displaying "Bob Smith, Alice Dupond" it displays "Smith, Dupond".

What I'd really like to do is map a list of tags to lowercase, e.g.:

{% set tags = ['Foo', 'Bar', 'Blah'] %}

{{ tags | map(t => "#{t}" | lower) | join(', ') }}

I've tried several variations, including:

• {{ tags | map(t => t | lower) | join(', ') }}
• {{ tags | map(t => t | lower()) | join(', ') }}
• {{ tags | map(t => t.lower) | join(', ') }}
• {{ tags | map(t => t.lower()) | join(', ') }}
• {{ tags | map(t => t | lower(t)) | join(', ') }}
• {{ tags | map(t => t.strtolower) | join(', ') }}
• {{ tags | map(t => t.strtolower()) | join(', ') }}

None of these work -- the output is always "Foo, Bar, Blah" -- yet none throw an error. It seems that anything I pass to the map filter it simply ignored. I wonder if the filter is being replaced by Pico's own map filter, which works as described here:

You can return all values of a given array key using the map filter (e.g. {{ pages|map("title") }} returns all page titles).

Any ideas?

Hi, PicoCMS not working with highers PHP versions (in my case 8.0). Error which I reciving:

NOTICE: PHP message: PHP Fatal error:  Unparenthesized `a ? b : c ? d : e` is not supported. Use either `(a ? b : c) ? d : e` or `a ? b : (c ? d : e)` in /var/www/html/vendor/twig/twig/lib/Twig/Node.php on line 42

As far as I found, PHP 7.4+ changing this: https://www.php.net/manual/en/migration74.deprecated.php

I think, this should be fixed because older versions are comming to end of life.

or maybe I missed something, and someone could help me.

Thanks for amaizing work!

Mentioned in #600.

Pico's markdown filter doesn't throw any errors. This is a different behavior to Twig's built in filters, which are very verbose and will print errors directly on the page if used incorrectly.

I accidentally fed the markdown filter an array a couple times and it just silently failed. 🤦🏻‍♀️

No idea if Pico's other filters are like this or not, but it's probably worth investigating.

Mentioned in #600

When you attempt to navigate to an underscore page (eg _meta), the entry for that page in the pages array is replaced with the contents of your 404 page (either the internal one or 404.md).

This can lead to some odd behavior if your theme is trying to access that underscore page, and also overall doesn't seem like it should be happening. 😉

(Ugh, and yes, that 👆🏻was the most readable issue title I could come up with... it took me a whole five minutes. 🤦🏻‍♀️)

@PhrozenByte don't feel the need to read or answer this all at once. I just didn't see the point of making multiple issues on very similar topics.

I've been laser focused on updating an old theme this week (Freelancer). It's gonna be pretty good. 😉

But, in the process I've had a few issues I wanted to discuss, especially considering the pico-theme.yml standard (and our as far as I can tell lack of documentation on it). (Okay, I lied here, it was like one question. 😂)

I've had a bunch of random thoughts and questions related to theming as I've been going, but I figured I'd hold them until the end and see what I couldn't just answer myself.

This is just meant to be a thread for a general discussion, not a singular issue. So, let's get into it.

1. The pico-theme.yml's meta-headers section doesn't seem to support arrays for having multiple levels of depth. Not sure whether this is an oversight or by design. The use case I'd describe here would be:

I have several meta-headers named portfolio_title, portfolio_divider, portfolio_nav and portfolio_disabled.

These could be written:

Portfolio Title: Recent Projects
Portfolio Divider: clock
Portfolio Nav: Projects
Portfolio Disabled: false

But I feel they'd look better as:

Portfolio:
  Title: Recent Projects
  Divider: clock
  Nav: Projects
  Disabled: false

It's fine if you've decided you just don't want Pico to have multi-level arrays of metadata, but I have been using them to simplify the YML on my themes for quite a while, lol. 😂

What are your thoughts on this? Is it an idea you absolutely hate or might it have potential?

Obviously in the meantime I can still accomplish this without registering them in pico_theme.yml (that's how I've been developing it anyway), they'll just have mandatory lower-case names like portfolio > title.

On a related side note, I almost opened this issue a few days ago to discuss how weird and inconsistent it feels when, if you don't register meta headers, they behave somewhat opposite of the built-in ones:

We typically write the meta headers with the first letter capitalized. When you do this, it then only presents itself as lowercase in Twig (eg Title becomes title). But if you have an unregistered custom header, the opposite becomes true. You write it with the first letter capitalized and it is only available the way you wrote it (Image stays Image).

I know why this is the case... it just feels odd and like it could be something of a trap for new users.

2. I've noticed that on some of my old themes (that I haven't got around to fixing yet), whitespace has started being removed by Twig. This has led to text beingcrushedtogether in some cases. Just curious if you knew when and why this behavior changed (besides the obvious "sometime between Pico 1 and 2 😂).

2. Is Twig's raw filter generally "safe" to use in Pico? I've been using it on this project more than I intended too because if I do anything to manipulate strings before printing them they become escaped, which doesn't work so well for HTML tags. 😅

It doesn't really seem like an issue considering our usual attitude toward security (that any access to Pico's files is the same level of security, and if someone had access to put something malicious in the markdown anyway, then they could probably already do a lot worse without caring about the Twig template, etc).

3. Pico's markdown filter doesn't seem to throw errors. This is a very different behavior to Twig's built in filters (which complain. A lot.). I accidentally fed it an array a couple times and it just silently fails. Compare this to Twig throwing an "Array to string conversion" notice every time I accidentally forget to json_encode my debug code (🤦🏻‍♀️), and I just feel like it should say something when you do it wrong. No idea if Pico's other filters are like this or not.

Do you think they should print errors for debugging?

4. It seems like having a _meta.md file is now an "officially endorsed" concept (at least in the docs). A lot of themes (Freelancer included) ignore index.md in favor of giving a custom front-page (or single-page) experience.

I like the idea of having theme-related/site-wide metadata in _meta.md (and it's what I've used this time), however, it does leave an awkward index.md-sized hole to be filled. 😉

Specifically, I mean you still require an empty index.md in this case, even if you're not using it, both for Pico's content folder detection and for preventing 404's (with the content dir manually specified in config.yml).

I guess this is mostly an opinion thing, but it leaves me wondering what approach is better in this case. If I use index.md for the metadata, it's at least used for something. The instructions wouldn't need a step that says "make sure you have an index.md, even if it's empty". What do you think? Would you rather themes suggest a blank index or that they forgo _meta.md in favor of sticking everything in index.md?

5. 404-ing on _meta.md behaves weird.

So, this theme rewrite is heavily dependent on _meta.md containing all its variables (don't worry, I've hard-coded defaults, so it all looks very professional even with an empty _meta.md 😉). I decided to test that Pico supposedly denies access to _ files, and I discovered an odd behavior. When it 404's on trying to access _meta.md... it also denies access to all the metadata I was accessing on _meta.md, causing my very customized site to revert to the demo data I've included.

Presumably this is happening because there's a shortcut somewhere in Pico that goes "I need to access this page. Oh, good, I'm already on it, I'll just look at current_page instead." Except its current page has been redirected to the 404 page. 🤦🏻‍♀️

Just kind of an odd quirk. I don't need it fixed or anything, just thought I'd bring it to your attention. 😂

6. Kind of surprised that using pages.pageid instead of pages["pageid"] still works. I'm assuming this is still just a legacy, compatibility behavior, since I remember you telling me a long time ago that it was preferred to use pages["pageid"] instead. I guess that's all, it was just kind of a "Huh... neat" moment. 🤷🏻‍♀️

7. This one should probably be a separate discussion entirely. Do you have any good suggestions for maintaining a large patch set against an upstream? The Twig bits I've written for Freelancer are exhaustively extensive. I've spent over a week on it now (while the Themes Gallery project hangs in limbo 😒). It just keeps going, lol. I need to stop adding things to it.

The original theme is written with Bootstrap, in SCSS and PUG. Since the Pico port is based on the compiled version, I can't exactly just grab the original repo as an upstream (though, maybe I could potentially pull from their compiled dist folder somehow).

At the moment, I plan to remove the upstream on my existing port (it was based on an out-of-date Jekyll version), and just replace the entire repo with the new version and sort this out later.

For future updates of Bootstrap and Freelancer though, it'd be nice to have a solution in place to be able to bring the changes forward without essentially starting from scratch every time.

At the moment, the best idea I'd have would be to diff the old and new Freelancer versions and simply use that to get a rough idea of what changed between versions. Or, you know, see if I could somehow make a patch file based on the diff between my version and theirs, but I think the changes might be too extensive for that (or at the very least, I might have to merge all my includes back into one mega-template). Either way, I don't see it being as easy as "fetch and merge upstream". 😩

So, if there's a fairly obvious solution you think I should look into, let me know. Not looking for a full solution, just a nudge in the right direction if you have any ideas. 😅

Alright, this has gone on long enough. I'm so ready to move on from this theme, but I keep finding one more thing to do.

And I promise the next one will be a "regular" theme. This one's just been needing some attention. 😉

Since the issues with our old dependencies kinda got out of hand lately (see #528, #534 and 8a44584291685e5e163765ed6578c184c991794e), it's time to kick-start development of Pico 3.0 :tada:

Major changes are going to be updated dependencies (Twig 3.0+ and Symfony YAML 5.0+) and lifting the requirements to PHP 7.2.5+. We definitely won't implement all of #317, but rather focus on lazy page discovery and loading. We definitely won't overhaul Pico's event system now, neither will we implement caching or i18n support with Pico 3.0 (maybe with Pico 3.1? :thinking:).

We'll also think about changing Pico's Markdown parser. Unfortunately Parsedown's development process got very unreliable lately. However, there's a lot to consider - not just BC, but also performance-wise (Parsedown is by far the most performant Markdown parser I know). Thus there's no decision made yet. Other opinions are very welcome on this topic! Also see e.g. #576

Pico 3.0 is a major release, thus it will break BC. As always, Pico's official PicoDeprecated plugin (Pull Request) will do its best to maintain BC. However, be warned, we'll explicitly drop all pre-v1.0 and v1.0 behaviour that affects performance.

As always, feedback is highly appreciated! :heart:

Ideas

• #581: Pico bundle package with various official plugins

Release of Pico v3.0.0-alpha.1

Since the mentioned issues are affecting live installations already, I decided to release a intermediate Pico v3.0.0-alpha.1. This release upgrades Pico's dependencies to Twig 2.12, Symfony YAML 3.4, Parsedown 1.7.4 and Parsedown Extra 0.8.1 for now (requiring PHP 7.0.8+). Both are still officially supported and are basically drop-in replacements, since they maintain BC on a best-effort basis ("best-effort" means "should work for most users", there can still be issues for some users). Pico v3.0.0-alpha.1 is meant as a fast solution for all people experiencing the issues mentioned above.

Feedback about Pico v3.0.0-alpha.1 is highly appreciated, especially regarding issues! :+1:

Related links

• List of ideas for Pico 3.0 and beyond
• PicoDeprecated pull request
• pico-theme pull request
• pico-composer pull request
• composer-installer pull request
• Website pull request
• Updated phpDoc class docs

Major changes

• Require PHP 7.0.8+
• Update dependencies: Twig 2.12, Symfony YAML 3.4, Parsedown 1.7.4 and Parsedown Extra 0.8.1; this is just an interim step, we'll update to Twig 3.0+ and Symfony YAML 5.0+ later
• …

Resolves #528, Resolves #534 Fixes #602, Fixes #603, Fixes #608