Pico's page tree is a list of all the tree's branches (no matter the depth). Thus, by iterating a array element, you get the nodes of a given branch. All leaf nodes do represent a page, but inner nodes may or may not represent a page (e.g. if there's a `sub/page.md`, but neither a `sub/index.md` nor a `sub.md`, the inner node `sub`, that is the parent of the `sub/page` node, represents no page itself).
A page's file path describes its node's path in the tree (e.g. the page `sub/page.md` is represented by the `sub/page` node, thus a child of the `sub` node and a element of the `sub` branch). However, the index page of a folder (e.g. `sub/index.md`), is *not* a node of the `sub` branch, but rather of the `/` branch. The page's node is not `sub/index`, but `sub`. If two pages are described by the same node (e.g. if both a `sub/index.md` and a `sub.md` exist), the index page takes precedence. Pico's main index page (i.e. `index.md`) is represented by the tree's root node `/` and a special case: it is the only node of the `` (i.e. the empty string) branch.
A node is represented by an array with the keys `id`, `page` and `children`. The `id` key contains a string with the node's name. If the node represents a page, the `page` key is a reference to the page's data array. If the node is a inner node, the `children` key is a reference to its matching branch (i.e. a list of the node's children). The order of a node's children matches the order in Pico's pages array.
If you want to walk the whole page tree, start with the tree's root node at `$pageTree[""]["/"]`. The root node's `children` key is a reference to the `/` branch at `$pageTree["/"]`, that is a list of the root node's direct child nodes and their siblings.
You MUST NOT iterate the page tree itself (i.e. the list of the tree's branches), its order is undefined and the array will be replaced by a non-iterable data structure with Pico 3.0.
Don't lower unregistered meta headers on the first level unsolicited (e.g. `SomeNotRegisteredKey: foobar` in the YAML Frontmatter should result in `['SomeNotRegisteredKey']`, not `['somenotregisteredkey']`). Furthermore, Pico no longer compares registered meta headers in a case-insensitive manner. However, you can now register multiple search strings that are used to find a registered meta header. This is achieved by flipping the meta headers array: Pico 2.0 uses the array key to search for a meta value and the array value to store the found meta value. Previously it was the other way round (what didn't make much sense...).
In the future we'll use picocms/pico-composer to create Pico's release packages (and picocms/pico-composer depends on picocms/pico-deprecated and picocms/pico-theme by default). Installing picocms/pico-deprecated and picocms/pico-theme is no longer required, but rather suggested. You simply don't need them in any case. You need picocms/pico-deprecated only if you're using old plugins, and picocms/pico-theme is obsolete when using a 3rd-party theme.
The performance vs. error-proneness trade-off doesn't justify this additional complexity. This is Pico 2.0, we always try to minimize BC-breaking changes, but we're breaking BC anyway by loading plugins from plugins/<plugin name>/<plugin name>.php only...
You can now explicitly specify both the `date_formatted` and `time` meta values to overwrite Pico's page date handling. Specifying `time` doesn't make much sense in general, however, specifying `date_formatted` allows you to use `{{ meta.date_formatted }}` on all systems, even those where `strftime()` doesn't work as wished
Daniel Rudolf