+{% endif %}
\ No newline at end of file
diff --git a/_includes/headInclude.html b/_includes/headInclude.html
index 0521450a..f560df13 100644
--- a/_includes/headInclude.html
+++ b/_includes/headInclude.html
@@ -3,32 +3,34 @@
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs.md b/docs.md
index 510328f6..73bff15e 100644
--- a/docs.md
+++ b/docs.md
@@ -1,11 +1,93 @@
---
layout: docs
+nav: 3
title: Docs
-headline: Pico Documentation
+headline: Table of Contents
description: |
- Pico is a flat file CMS, this means there is no administration backend or database to deal with.
- You simply create .md files in the "content" folder and that becomes a page.
-collection: docs
-nav: 3
-redirect_from: /docs.html
+ Pico is stupidly simple, but incredibly powerful.
+ But with great power comes a little bit of a reading responsibility.
+# That power comes with a little bit of reading though.
+toc:
+ installing-and-configuring-pico: Installing and Configuring Pico
+ creating-content: Creating Content
+ theming-with-twig: Theming with Twig
+ deconstructing-the-defaults: Deconstructing the Defaults
+ twig-tips-and-tricks: Twig Tips and Tricks
+ the-power-of-plugins: The Power of Plugins
---
+
+
+
+
+
+
+
+## [Installing and Configuring Pico][Installing]
+
+
+There are many options for downloading and installing Pico. From automated choices like Composer and Git to just downloading an old-fashioned zip file. There's even a version of Pico available on the Nextcloud App Store.
+
+This guide will cover all the basics of getting Pico installed, configuring your webserver (whether you use Apache, Nginx, Lighttpd, or Caddy), to configuring Pico itself.
+
+If you're new to Pico altogether, you'll probably want to start here, and make your way through each section as you go.
+
+
+
+
+## [Creating Content][CreatingContent]
+
+Pico's flat file approach makes creating content a breeze. This guide discusses the basics of using Pico. We'll go over the URL structure of Pico's content folder, the YAML/Markdown format of your content files, and where you should put your assets.
+
+
+
+
+
+
+## [Theming with Twig][Theming]
+
+Twig is an incredibly powerful templating language. In this guide, we'll go over how Pico Themes work, how to access the extra Twig variables and filters Pico provides, and point you to some Twig related learning resources.
+
+
+
+
+
+
+## [Deconstructing the Defaults][DeconstructingDefaults]
+
+The best way to learn is through example, right? Here we break the Default Theme down into bite sized code snippets and explain what the Twig code is doing in them. A lot of the code you'll see will be similer, if not identical, to what you'll need for your own projects. You can even copy them if you'd like.
+
+
+
+
+## [Twig Tips and Tricks][TwigTips]
+
+Moving on from the Default Theme, here we'll look at some more advanced examples of tricks you can pull off with Pico and Twig. We'll take a look at how to implement some blogging features as well, like pagination, tagging, and search.
+
+
+
+
+
+
+
+## [The Power of Plugins][Plugins]
+
+So you've mastered the power offered by Twig and you're still wanting more?
+
+Welcome to the world of Plugins. Pico is incredibly extendable via its Plugin system. Utilizing PHP, you can easily hook into Pico to create your own custom functionality.
+
+
+
+
+
+
+
+[Installing]: {{ site.github.url }}/guide/installing
+[CreatingContent]: {{ site.github.url }}/guide/creating-content
+[Theming]: {{ site.github.url }}/guide/theming-with-twig
+[DeconstructingDefaults]: {{ site.github.url }}/guide/deconstructing-the-defaults
+[TwigTips]: {{ site.github.url }}/guide/twig-tips-and-tricks
+[Plugins]: {{ site.github.url }}/guide/plugins
diff --git a/guide/creating-content.md b/guide/creating-content.md
new file mode 100644
index 00000000..d11a6754
--- /dev/null
+++ b/guide/creating-content.md
@@ -0,0 +1,256 @@
+---
+layout: docs
+nav-url: /docs/
+title: Creating Content
+headline: Creating Content in Pico
+description: |
+ Markdown and YAML make creating content in Pico a breeze.
+ Let's discuss these formatting syntaxes and how they relate to Pico.
+toc:
+ simple-but-elegant-content-management:
+ _title: Simple But Elegant Content Management
+ the-content-folder: The Content Folder
+ all-about-urls: All About URLs
+ yaml-and-markdown:
+ _title: YAML and Markdown
+ yaml---yay-a-metadata-lesson: YAML - Yay, A Metadata Lesson
+ markdown---because-why-mark-up: Markdown - Because Why Mark *Up*?
+ variable-variables: Variable Variables
+ lets-get-started:
+ _title: Let's Get Started
+ somewhere-to-land: Somewhere to Land
+ 404-heading-not-found: 404 Heading Not Found
+ images-downloads-and-other-assets: Images, Downloads, and Other Assets
+ to-blog-or-not-to-blog: To Blog or Not to Blog
+---
+
+## Simple But Elegant Content Management
+
+Pico's flat file nature is a simple approach to content management. Pico has no dashboard or admin panel. There's no clunky interface for creating posts or pages.
+
+In all their efforts to be all-in-one solutions, many CMS's provide an overwhelming amount of options, metadata, interfaces within interfaces, and other overhead to worry about.
+
+Pico is simple: You just create a file and write.
+
+### The Content Folder
+
+Let's start with the most basic question, "Where do I put my content?".
+
+In Pico, your website's pages are created from [Markdown][] (`.md`) files, which live in your `content` folder.
+
+Publishing a new page to your Pico site is as simple as dropping a new `.md` file in this folder. You can even organize your pages into subfolders if you'd like.
+
+Pages get their URL from their path and filename, so keep this in mind when naming and organizing them.
+
+You'll want to start with an `index.md` file which will act as the landing page for your site. We'll dive deeper into creating those pages soon.
+
+Keep in mind, the `content` folder is for *Markdown only*. If you're using our recommended [webserver configuration][WebserverConfig], this folder won't be accessible to the outside world. We'll go over where you can put the rest of [your assets][Assets] in a bit.
+
+#### The Sample Contents
+
+You'll notice when you first navigate to your Pico site that there's already content here, even though you haven't added anything to the `content` folder.
+
+You've just discovered the Sample Contents! Pico includes these pages internally and displays them whenever your own content is missing. Don't worry, as soon as you add your own `index.md` to the `content` folder, Pico will automatically switch to displaying *your* content instead of its own.
+
+The Sample Contents can also be a quick reference for what content files should look like. You can view the source for these files on [GitHub][SampleContents]. Just be sure to enter the Source View of the files with the `< >` button, as GitHub defaults to showing you the *Rendered* Markdown content.
+
+Also contained within the Sample Content is a [Theme Styling Test][ThemeTest] page you might find useful if you decide to create your own [Pico Theme][Theming].
+
+### All About URLs
+
+When using Pico, each one of your Markdown files gets a URL based on its folder path and filename. Inside the `content` folder, a file named `about.md` would have a url like `example.com/about`, while a file at `projects/my-awesome-project.md` would be viewable at the url `example.com/projects/my-awesome-project`. Pretty simple, right?
+
+These URLs are examples with [URL Rewriting][WebserverConfig] enabled. Without it, they'll have a question mark `?` in them after the root address, like `example.com/?about` and `example.com/?projects/my-awesome-project`.
+
+Your `index.md` always acts as the root `/` of your website. It's the page you see when you navigate to `example.com`.
+
+Subfolders can also have an `index.md` if you'd like. You can put the index page for your subfolder at either `subfolder.md` or `subfolder/index.md`. Pico will turn either file location into `example.com/subfolder/`, however Pico will *prioritize* `subfolder/index.md` if both files exist! Use whatever location works best for you.
+
+
+
+Now that you know how Pico generates urls, let's learn how to actually *create* that content!
+
+## YAML and Markdown
+
+[YAML][] and [Markdown][] are a common pair in today's world, possibly due to the popularity of GitHub. YAML provides an easy to understand syntax for your pages' metadata while Markdown provides easy, plain-text formatting of your content. The pair make a great combination, and once you learn them you'll find it hard to disagree.
+
+### YAML - Yay, A Metadata Lesson
+
+Writing your metadata in YAML is as easy as writing it out. Each of your content files in Pico will begin with a "YAML Header". It will look something like this:
+
+```
+---
+Title: Welcome
+Description: Welcome to my website, where we discuss the finer points of Pico.
+Author: Joe Bloggs
+Date: 2013/01/01
+Robots: noindex,nofollow
+Template: index
+---
+```
+
+Simple, huh? And it gets better too. These are all the variables that Pico supports by default, but none of them are *required* for your page to work. The only "required" item on the list above is "Title", because Pico's Default Theme uses the page Title in order to link to it.
+
+
+
+
+Each of these metadata fields are utilized by your Pico theme. Some themes may add or require additional fields in order to function. We'll go into that in more detail about these when we discuss [Theming with Twig][Theming]. For now, stick with Title, Description, Author, and Date, as these are things most pages should probably have.
+
+### Markdown - Because Why Mark *Up*?
+
+
+
+Markdown makes formatting your pages simple and intuitive. According to its creator, John Gruber, "Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)."
+
+
+
+Sounds good, right? When writing your Pico content files, you get to use the formatting power of [Markdown], [Markdown Extra][MarkdownExtra], and regular HTML.
+
+For simplicity, you'll want to stick with Markdown/Markdown Extra wherever you can, but on occasion you may want more control. You can use regular HTML code within your document, but be aware that within HTML tags, Pico will not process Markdown.
+
+### Various Variables
+
+When writing your content, there are also some variables you can use to make your life easier. By inserting these into your markdown, you can use their values dynamically in your pages.
+
+* `%site_title%` - The title of your Pico site.
+* `%base_url%` - The URL of your Pico site. Internal links can be ~~specified using~~ written as `%base_url%/sub/page` (`%base_url%?sub/page` without URL rewriting).
+* `%theme_url%` - The URL to the folder of your current theme.
+* `%meta.*%` - By using the `meta` variable, you can access any YAML variable of the current page, for example, `%meta.author%` would be replaced with `Joe Bloggs` in our YAML example above.
+
+
+
+## Let's Get Started
+
+Now that we know the basics of creating pages in Pico, we can start generating our own content. Remember, every page starts with a YAML header before the markdown starts. ~~If you're ever unsure of how this should look, you can check out some of the files in `content-sample`.~~
+
+### Somewhere to Land
+
+The first page you'll want to create is your "index" or "landing page". This is the file that will be loaded when a user visits the `base_url` of your Pico site. Start by creating a blank file named `index.md` in the `content` folder. In the previous section, we discussed how to use YAML and Markdown to create your content. Use what you've learned to create a landing page worth visiting!
+
+### 404 Heading Not Found
+
+If Pico cannot find a given file, it'll show the content of its internal 404 warning page. This content is loaded in your theme just like any other page, so it makes for a very plesent looking error message. Well, as plesent as an error can be anyway.
+
+However, if you'd like, you can also create your own customized 404 page. Just create a file at `content/404.md` and Pico will use that instead of its own.
+
+You can also add `404.md` to any subfolder and it'll become the 404 page for that folder. For example, if you wanted to have a special 404 error page for your blog, you might create this file at `content/blog/404.md`.
+
+
+
+### Images, Downloads, and Other Assets
+
+So, you're typing away, creating some content, when you think, "I'd like to put an image here". You link to an image within your content folder, only to discover that it the image generates a 404 error.
+
+If you're using our recommended [Apache][ApacheConfig] or [Nginx][NginxConfig], this happened because we deny access to the content folder by default for security reasons. You probably don't want somebody else probing around in your site's content folder either.
+
+
+
+Instead, all images, downloads, and other website assets should be placed in the `assets` folder. You'll find this location in the root of your Pico install. How you choose to organize this folder is entirely up to you.
+
+It may seem counter-intuitive at first, but ultimately, we feel it's tidier this way. It stops your content folder from being overrun with files that don't belong there.
+
+It's easy to link to an item in your assets folder, just use `%assets_url%` in your Markdown. For example ``.
+
+
+
+### To Blog or Not to Blog
+
+Pico is *not* blogging software. That being said, It is fairly easy to create a blog using Pico, as long as you're aware of it's limitations. Pico lacks many standard blogging features, such as authentication, tagging, pagination, and social features. There are third party plugins available to help bridge this gap though.
+
+Also, Twig itself is a pretty powerful templating language. If you're determined, you can actually implement many of these features right at the theme level!
+
+In the not-too-distant future, `Pico 2.0` will ship with optional, but officially supported blogging plugins and tools. We've even got an official editor in the works, so stay tuned.
+
+
+
+In the meantime, see what you can do with the current version. You'll find that Pico is incredibly extendable.
+
+Check out our [Cookbook][] for some tips and code snippets that will help you use Pico for [blogging][CookbookBlogging].
+
+
+
+---
+
+## Up Next...
+
+You've installed Pico and now you've created a simple page or two. What now? Well, Pico's default theme is a little sparse. It's not really meant to be used in production, but rather as a learning resource. The default theme provides a great example of how to implement Pico's most basic features.
+
+
+
+But if all you've used is the Default Theme, you've only scratched the surface of what Pico is really capable of. The real power of Pico is in customizing it to meet your own needs!
+
+How do you do this though? That's what our next guide will cover. You'll learn how to customize Pico using the powerful template engine, Twig. Click through to proceed to the next article. We'll see you there!
+
+{: .aligncenter}
+[Theming with Twig][Up Next]{: .button}
+
+
+[Up Next]: {{ site.github.url }}/guide/theming-with-twig
+
+[InlineReadme]: {{ site.gh_project_url }}/blob/master/content-sample/index.md
+[YAML]: https://en.wikipedia.org/wiki/YAML
+[Markdown]: http://daringfireball.net/projects/markdown/syntax
+[MarkdownExtra]: https://michelf.ca/projects/php-markdown/extra/
+[Cookbook]: {{ site.github.url }}/cookbook/
+[CookbookBlogging]: {{ site.github.url }}/cookbook/#BloggingWithPico
+[Theming]: {{ site.github.url }}/guide/theming-with-twig
+
+
+[WebserverConfig]: {{ site.github.url }}/guide/installing#web-server-configuration
+[Assets]: #images-downloads-and-other-assets
+[SampleContents]: {{ site.gh_project_url }}/tree/{{ site.gh_project_branch }}/content-sample
+[ThemeTest]: {{ site.gh_project_url }}/blob/master/content-sample/theme.md
+[Theming]: {{ site.github.url }}/guide/theming-with-twig
+
+
+
+{% comment %}
+
+* Move existing [blogging section](http://picocms.org/docs/#blogging) (shown below) to cookbook OR its own bloggin page.
+
+* Capt America meme "So you want to make a blog?"
+
+---
+
+### Blogging
+
+Pico is not blogging software - but makes it very easy for you to use it as a blog. You can find many plugins out there implementing typical blogging features like authentication, tagging, pagination and social plugins. See the below Plugins section for details.
+
+If you want to use Pico as a blogging software, you probably want to do something like the following:
+
+
+ Put all your blog articles in a separate blog folder in your content directory. All these articles should have both a Date and Template meta header, the latter with e.g. blog-post as value (see Step 2).
+
+
+ Create a new Twig template called blog-post.twig (this must match the Template meta header from Step 1) in your theme directory. This template probably isn't very different from your default index.twig, it specifies ow your article pages will look like.
+
+
+ Create a blog.md in your content folder and set its Template meta header to e.g. blog. Also create a blog.twig in your theme directory. This template will show a list of your articles, so you probably want to do something like this:
+
+ {% raw %}
+ Make sure to exclude blog articles from your page navigation. You can achieve this by adding {% if not (page.id starts with "blog/") %}...{% endif %} to the navigation loop ({% for page in pages %}...{% endfor %}) in your theme's index.twig.
+
+
+{% endcomment %}
\ No newline at end of file
diff --git a/guide/deconstructing-the-defaults.md b/guide/deconstructing-the-defaults.md
new file mode 100644
index 00000000..40a8a173
--- /dev/null
+++ b/guide/deconstructing-the-defaults.md
@@ -0,0 +1,252 @@
+---
+layout: docs
+nav-url: /docs/
+title: Deconstructing the Defaults
+headline: Deconstructing the Defaults
+description: |
+ The best way to learn is through example, right?
+ Let's break down the Default Theme and examine it piece by piece.
+toc:
+ customization:
+ _title: Customization
+ themes:
+ _title: Themes
+ dealing-with-pages: Dealing with pages
+ twig-filters-and-functions: Twig filters and functions
+ plugins: Plugins
+---
+
+
+
+Pico's [Default Theme][PicoTheme] is intentionally simple and straightforward. You can consider it the "reference implementation" of Pico's default functionality. A lot of the code you see here will be similar, if not identical, to what you'll need for your own projects. The Default Theme itself can also act as a good starting template for building your own theme.
+
+The best way to learn is through example, right? Let's get started breaking down the Default Theme into bite sized code snippets. As we go, we'll stop to explain all the Twig code and what it's doing.
+
+
+
+
+
+
+
+
+
+
+
+## It's all in your Head
+
+There's nothing overly complicated about the `head` section of your Pico page. The Twig bits mostly involve using simple logic to check if the user defined a few variables, then adding them to the HTML `head`.
+
+
+### Title and Description
+{% raw %}
+```twig
+{% if meta.title %}{{ meta.title }} | {% endif %}{{ site_title }}
+{% if meta.description %}
+
+{% endif %}
+```
+{% endraw %}
+
+Here we have an HTML Title tag, providing the page title. In the example, we check if the page has a `meta.title`, then if so, we print the title followed by an I-bar separtor `|` and the `site_title`. With this setup, your page would look something like "My Page Title \| My Website" in the browser's tab or titlebar.
+
+Next, if there's a `meta.description` for the page, we add that to the HTML as well. In this case, we've run it through Twig's `striptags` filter to remove any formatting the user may have provided. While we may want this formatting later when we're building the page itself, remember, we're still filling out the head! It's not going to be happy with some extra tags jammed in there.
+
+#### Some Statements on If Statements
+
+Both of these examples check `if` a variable exists before printing the corresponding code. In Twig, you can check for the existance of any variable with simple `if` statements like these.
+
+It's a little more complicated than that, Twig's just good at figuring out what should evaluate to `true` and what should evaluate to `false`. You can check the Twig Docs on [If Statements][TwigIF] for more information. Generally though, if something seems like it should be false, like `null`, `0`, an empty array `[]`, or of course `false`, it will be. Almost everything else evaluates as `true`.
+
+Be warned though, this can sometimes get a little confusing. A variable that isn't defined and a variable that is explicitly set to `false` will look identical to this simple `if` statement. If you ever need to know that something was intentionally set to `false`, you should also check if it `is defined`.
+
+As you can see, unlike some languages, Twig won't crash from trying to access a variable that doesn't exist. It just returns `null` instead. In Pico, this is because Twig's `strict_variables` option defaults to `false`. If you enable `strict_variables` in either your `config.yml` or `pico-theme.yml`, Twig will instead throw an error in these situations.
+
+
+
+
+
+
+
+
+### Robots
+{% raw %}
+```twig
+{% if meta.robots %}
+
+{% endif %}
+```
+{% endraw %}
+
+Does not compute? Don't worry about it. This bit is to set up the HTML `robots` meta tag, which allows you to tell some search engines whether or not to crawl a particular page. Including this in your theme is nice touch (Pico even defines the `Robot` metadata header out-of-the-box), but its entirely optional. When in doubt, just copy this block as is, and it'll be there for anyone that wants it.
+
+### Canonical URL
+{% raw %}
+```twig
+{% if current_page %}
+
+{% endif %}
+```
+{% endraw %}
+
+Another bit for your friendly neighborhood webcrawler. The `canonical` tag tells search bots the proper URL to index your page as. This can help them to filter out things like query strings and redirected links that might otherwise confuse them. Again, this is optional, but it really doesn't hurt to include it.
+
+
+
+### Stylesheets
+{% raw %}
+```twig
+
+
+
+```
+{% endraw %}
+
+You probably want to link some stylesheets or Javascript to your theme. The best way to do this is using `theme_url` to get the location of your specific theme's folder. This will make sure those resourses always get found, no matter what your Pico installation looks like.
+
+## Navigation
+
+
+
+
+### Site Logo
+{% raw %}
+```twig
+{% if pages["_meta"].meta.logo %}
+
+{% endif %}
+```
+{% endraw %}
+
+This one's not too hard, but there's a few different things going on. First, we check if the user has filled out the `Logo:` metadata property in their `_meta.md` page (if not, that's it, we stop there).
+
+Next, we're making a link to the `index` page using the `link` filter. This will generate a proper link to the `index` page regardless of whether the user has [URL Rewriting][] enabled or not. It's the recommended way to manually link to your content pages.
+
+Finally, we attach an image using the `meta.logo` property from `_meta.md` as our source URL. We run it through the `url` filter to make sure any of Pico's [URL variables][], like `%base_url%` and `%assets_url%` get replaced in the output.
+
+
+
+
+
+### Site Title and Tagline
+{% raw %}
+```twig
+
+```
+{% endraw %}
+
+#### A Tangent about Ternaries
+
+The first thing to look at in this example is the outer containing `div` tag. There's an interesting code snippet we haven't seen before here. This bit of code uses a Ternary Operator, which is like a condensed `if else` statement. It's definitely more of an advanced syntax, but it can be really helpful in places where a traditional `if else` block of code would be cumbersome.
+
+In our example, we're asking "Does `meta.tagline` (on `_meta.md`) exist? If so, print `' class="tagline"'` to the page." So, if a user has defined the `Tagline:` meta property, this `div` will have an extra `class` on it that it wouldn't otherwise have (allowing us to apply some extra styles in our CSS). In most cases, a Ternary statement is formatted `condition ? response_if_true : response_if_false`, though you'll notice in the example, we aren't actually doing *anything* if false.
+
+
+
+
+
+### For Page in Pages()
+
+{% raw %}
+```twig
+
+
+ {% for page in pages(depthOffset=-1) if not page.hidden %}
+
+ {{ page.title ?: page.id }}
+
+ {% endfor %}
+
+
+```
+{% endraw %}
+
+"For Page in Pages()" has a nice rhyme to it, huh? Need to access your Pages? This simple `for` loop is usually how you'll do it.
+
+In our example, the pages() function is given `depthOffset=-1` that way it'll also return the `index` page in its results. So, we're looping through each `page` that the `pages()` function returns, as long as that page isn't `hidden` (meaning it has `Hidden: true` in its metadata).
+
+Next, as we're building our navigation list, we check if the page `id` we're looking at matches the `id` of the `current_page`. If so, we add the `active` class to that list item for styling.
+
+Finally, we link to the page's `url`, using the page `title` for the link text if it exists. If there's no title, we fall back to using the page's `id`.
+
+You'll notice this looks similar to the [Ternary Operator][] we discussed above. This time, it's a shorthand version which equates to "Is there a `page.title`? If so, use that. If not, use `page.id` instead."
+
+## Page Content
+
+{% raw %}
+```twig
+
+
+ {{ content }}
+
+
+```
+{% endraw %}
+
+What, you were expecting something hard? `{% raw %}{{ content }}{% endraw %}` will print the Markdown processed content of the current page. Navigate to a different page, you'll see different content. Easy as that.
+
+## Social Links
+
+{% raw %}
+```twig
+
+```
+{% endraw %}
+
+Let's look at how the Default Theme handles social links. Like Logo and Tagline, these are extra metadata headers defined in `pico-theme.yml`.
+
+Here we have another `for` loop, but this time we aren't iterating over `pages()`. Instead, we're looking at each entry within the `social` header. For each item, we're making a new link and filling out the details with the item's `url`, `title`, and `icon`. Nothing we haven't seen before here.
+
+The only thing special to note is that `social.icon` is only *half* the class name. The Default Theme uses [Fontello][] for icons, which uses the convention of starting every name with `icon-`. To make it simpler for the end user, the `icon-` part is hardcoded here and they'll only have to provide the specific icon's name. This is a fairly typical practice for web icons, [Font Awesome][] for example often starts theirs with `fa-`. While it's certainly not a Pico specific thing, keeping the user experience in mind almost always results in better code!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+---
+
+## Up Next...
+
+Where to go from here. Two choices.
+
+
+{: .aligncenter}
+[Twig Tips and Tricks][UpNext]{: .button}
+[Not More Examples][SkipAhead]{: .button}
+
+
+[UpNext]: {{ site.github.url }}/guide/deconstructing-the-defaults
+[SkipAhead]: #
+
+[TwigIF]: https://twig.symfony.com/doc/1.x/tags/if.html
+[PicoTheme]: https://github.com/picocms/pico-theme
\ No newline at end of file
diff --git a/guide/installing.md b/guide/installing.md
new file mode 100644
index 00000000..6baa331b
--- /dev/null
+++ b/guide/installing.md
@@ -0,0 +1,453 @@
+---
+layout: docs
+nav-url: /docs/
+title: Installing and Configuring Pico
+headline: Installing and Configuring Pico
+description: |
+ Installing Pico couldn't be easier.
+ This guide will cover everything you need to know to get Pico up and running.
+toc:
+ incredible-install-options:
+ _title: Incredible Install Options
+ composer: Composer
+ pre-bundled-release: Pre-Bundled Release
+ git: Git
+ git-development: Git (Development)
+ nextcloud: Nextcloud
+ web-server-configuration:
+ _title: Web Server Configuration
+ apache: Apache
+ nginx: Nginx
+ lighttpd: Lighttpd
+ caddy: Caddy
+ configuring-pico: Configuring Pico
+components:
+ PicoTheme: https://github.com/picocms/pico-theme
+ PicoDeprecated: https://github.com/picocms/pico-deprecated
+ PicoComposer: https://github.com/picocms/pico-composer
+galleries:
+ standalone_1:
+ style: magnify
+ images:
+ -
+ heading: Installation is Easy!
+ description: |
+ Simply upload Pico's files to your server and you're done!
+ This is what Pico's folder looks like after installation.
+ thumbnail: /style/images/docs/about/thumbnails/pico_folder.png
+ fullsize: /style/images/docs/about/fullsize/pico_folder.png
+ styles: "float: right; margin-left: 2em;"
+ standalone_2:
+ style: magnify
+ images:
+ -
+ heading: Configuration is Easy Too!
+ description: Configuring Pico is as simple as uncommenting a few lines in the included config template.
+ thumbnail: /style/images/docs/about/thumbnails/config.png
+ fullsize: /style/images/docs/about/fullsize/config.png
+ styles: "float: right; margin-left: 2em;"
+---
+
+Installing Pico is as simple as uploading it to your webserver. Seriously. But while we could just leave it there, this guide will dive much deeper, covering all you'd ever need to know on the subject.
+
+Pico's only system requirement is a webserver with PHP 5.3.6 or greater, with the `dom` and `mbstring` extensions enabled.
+
+## Incredible Install Options
+
+
+
+Pick your poison! Pico has quite a few supported installation methods. Pick whichever strategy that works for you best.
+
+{% include buttonGroupNav.html mode="buttons" buttons = "Composer, Pre-bundled Release, Git, Git (Development), Nextcloud" %}
+
+
+
+
+{% include buttonGroupNav.html mode="start" id="Composer" %}
+
+### Composer
+
+Do you have shell access to your webserver? If so, try [Composer]!
+
+Using Composer to install Pico provides a great user experience. Composer makes maintaining and updating your Pico install a breeze.
+
+We'd really recommend you try it!
+
+Simply run the following commands to install Composer, then use Composer to install Pico for you.
+
+```shell
+$ curl -sSL https://getcomposer.org/installer | php
+$ php composer.phar create-project picocms/pico-composer pico
+```
+
+That's it! You'll thank us (and Composer) when it's time to update!
+
+(It's as simple as running `php composer.phar update` in your Pico folder.)
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Pre-bundled Release" %}
+
+### Pre-Bundled Release
+
+Not interested in an automated solution? That's okay, you can install Pico manually too.
+
+{: .aligncenter}
+[Download Pico][LatestRelease]{: .button}
+
+You can always find Pico's [Latest Release][LatestRelease] on our GitHub Page.
+
+This pre-bundled release comes with all the dependencies necessary for Pico to run.
+
+Simply upload the extracted files to the `httpdocs` directory (e.g. `/var/www/html`) of your server.
+
+If you're using Apache, there's also an included `.htaccess` file provided for automatic configuration. If you're running Linux or macOS, double check that you've uploaded this file, as it likes to hide!
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Git" %}
+
+### Git
+
+Using Pico together with Git, you can create a powerful, version controlled, and perhaps even collaborative workflow. The possibilities are endless!
+
+To get you started, Pico has a ready to go [Composer starter project][PicoComposerGit] you can [fork right on on GitHub][HelpFork]!
+
+Our recommended Git workflow is:
+
+1. Fork the [starter project][PicoComposerGit] on GitHub. (If you'd rather not use GitHub, just clone it locally and manually add your new remote to the repo.)
+
+2. Clone the fork to your local computer. Add whatever assets, content, plugins, and themes you'd like and commit them to the repo. Push the changes back to GitHub (or your own remote).
+
+3. On your webserver, navigate to your `httpdocs` folder. Simply run the following commands to install Composer, then use Composer to install Pico's dependencies for you (substituting your own Git remote if applicable).
+
+ ```shell
+ $ curl -sSL https://getcomposer.org/installer | php
+ $ git clone https://github.com// pico
+ $ php composer.phar --working-dir=pico install
+ ```
+
+4. Next time you commit updates your Pico site repo, just run `git pull` in this folder on your webserver to update it. You can even update Pico and its dependencies with a simple `php composer.phar update`.
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Git (Development)" %}
+
+### Git (Development)
+
+Our recommended development workflow is to start with Pico's [Composer starter project][PicoComposerGit] and use Git to pull in all of Pico's components as "local packages" for Composer.
+
+This is a bit more involved than any other installation method, and of course also implies you'll be using the current *development* version of Pico, which is likely *unstable* and *not ready for production use*!
+
+1. On your webserver, navigate to your `httpdocs` directory and make a new folder for Pico (e.g. `/var/www/html/pico`). Download and extract Pico's Composer starter project into the `workspace` directory:
+
+ ```shell
+ $ curl -sSL {{ page.components.PicoComposer }}/archive/master.tar.gz | tar xz
+ $ mv pico-composer-master workspace
+ ```
+
+2. Clone the Git repositories for all Pico components (Pico's core, Pico's Default Theme and the `PicoDeprecated` plugin) into the `components` directory:
+
+ ```shell
+ $ mkdir components
+ $ git clone {{ site.gh_project_url }}.git components/pico
+ $ git clone {{ page.components.PicoTheme }}.git components/pico-theme
+ $ git clone {{ page.components.PicoDeprecated }}.git components/pico-deprecated
+ ```
+
+3. Update the `composer.json` of your development workspace (i.e. `workspace/composer.json`) to instruct Composer to use the local Git repositories as replacement for the `picocms/pico` (Pico's core), `picocms/pico-theme` (Pico's Default Theme) and `picocms/pico-deprecated` (the `PicoDeprecated` plugin) packages.
+
+ ```json
+ {
+ "repositories": [
+ {
+ "type": "path",
+ "url": "../components/pico",
+ "options": { "symlink": true }
+ },
+ {
+ "type": "path",
+ "url": "../components/pico-theme",
+ "options": { "symlink": true }
+ },
+ {
+ "type": "path",
+ "url": "../components/pico-deprecated",
+ "options": { "symlink": true }
+ }
+ ],
+ "require": {
+ "picocms/pico": "dev-master",
+ "picocms/pico-theme": "dev-master",
+ "picocms/pico-deprecated": "dev-master",
+ "picocms/composer-installer": "^1.0"
+ }
+ }
+ ```
+
+4. Download Composer and run it with the `install` option:
+
+ ```shell
+ $ curl -sSL https://getcomposer.org/installer | php
+ $ php composer.phar --working-dir=workspace install
+ ```
+
+That's it! You're now running the development version of Pico.
+
+By the way, you can also find all of Pico's components on [Packagist.org][Packagist]: [Pico's core][PicoPackagist], Pico's [Default Theme][PicoThemePackagist], the [`PicoDeprecated` plugin][PicoDeprecatedPackagist] and Pico's [Composer starter project][PicoComposerPackagist].
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Nextcloud" %}
+
+### Nextcloud
+
+Pico for Nextcloud offers a powerful combination of admin features, like those you'd find in a traditional CMS.
+
+If you're already running Nextcloud on your webserver, you can install Pico as a Nextcloud App and take advantage of their combined features.
+
+Just look for Pico CMS in Nextcloud's App Store. Hit the "Download and Enable" button and you're done!
+
+You can then configure Pico within Nextcloud's settings.
+
+You'll find Pico's configuration divided between Nextcloud's "Personal" and "Administration" sections.
+
+Administration allows you to add custom themes, plugins, and templates to Pico, as well as tweak some advanced settings.
+
+Each Nextcloud users also has their own Personal section, where they can configure their own personal Pico website.
+
+{% include buttonGroupNav.html mode="end" %}
+
+
+
+
+
+## Web Server Configuration
+
+While Pico generally works out-of-the-box, there are a few things we can tighten up with some additional configuration.
+
+First, we *absolutely* recommend that you tighten up security by restricting visitor access to Pico's folder structure. There's no reason we need our visitors peeking around at our `config.yml` or raw `content` files, among other things (even if no real harm would likely come of it).
+
+Second, you may have noticed that out-of-the-box, Pico's urls have an odd question mark `?` in them.
+
+By default, Pico's URLs look like this: `http://example.com/pico/?sub/page`. It's not horrible, but some might find this question mark a little bit "unsightly" on a production website.
+
+That is where Pico's optional URL Rewriting comes in. It takes the `?` out of the URL, turning `http://example.com/pico/?sub/page` into `http://example.com/pico/sub/page`.
+
+### Server Specific Instructions
+
+How you accomplish these things varies a lot between web servers, so we've included instructions for most of the popular options out there.
+
+As always, if you need some additional assistance, please refer to our ["Getting Help"][GettingHelp] page.
+
+{% include buttonGroupNav.html mode="buttons" buttons = "Apache, Nginx, Lighttpd, Caddy" %}
+{% include buttonGroupNav.html mode="start" id="Apache" %}
+
+### Apache
+
+If you're using Apache, you're in luck: Our included `.htaccess` file will take care of the configuration for you automatically.
+
+If you have any issues, just make sure that both [`mod_rewrite`][ModRewrite] and `.htaccess` overrides are enabled.
+
+
+
+
+#### Troubleshooting (Tentative heading)
+
+If you're getting `404 Errors` or if Pico's still adding `?` to your URLs, you'll want to make sure Apache is configured right. The location of Apache's config file (or files) depends on your Linux Distribution (for example, `/etc/httpd/httpd.conf`, `/etc/httpd/conf/httpd.conf`, or `/etc/apache2/httpd.conf`).
+
+Your config file should have a line similar to `LoadModule rewrite_module modules/mod_rewrite.so` in it enabling `mod_rewrite`. Make sure this line isn't commented out!
+
+You'll also want to make sure that `.htaccess` overrides are allowed, by setting `AllowOverride All` in either your global Apache config or in your virtual host config file (often located in a subfolder of your Apache config, such as `vhosts` or `sites-available`).
+
+If you get a `500 Internal Sever Error`, try removing the last line of `.htaccess`, which declares some extra `Options`. For security reasons, this declaration disables `Indexes` and `MultiViews` to prevent visitors from being able to browse your raw files. However, if your web host has configured Apache to not allow option setting, this line will cause it to throw a `500 Error`.
+
+In rare cases where you have URL Rewriting working, but Pico is still adding `?` to your URLs, you can manually override Pico's behavior by setting `rewrite_url: true` in your `config.yml`.
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Nginx" %}
+
+### Nginx [Learn more…][NginxConfig]{:.learn-more}
+{:#nginx}
+
+If you're using Nginx, configuration is a little more involved than Apache. We have an entire [Nginx Guide][NginxConfig] to help walk you through the process.
+
+
+
+The following configuration excerpt is somewhat of a "tl;dr" version of a very extensive topic. It should provide the *bare minimum* configuration you need for Pico. If you have any trouble, please read all of the aforementioned [Nginx Guide][NginxConfig]. For additional assistance, please refer to our ["Getting Help"][GettingHelp] page.
+
+```
+location ~ ^/pico/((config|content|vendor|composer\.(json|lock|phar))(/|$)|(.+/)?\.(?!well-known(/|$))) {
+ try_files /pico/index.php$is_args$args =404;
+}
+
+location /pico/ {
+ index index.php;
+ try_files $uri $uri/ /pico/index.php$is_args$args;
+}
+```
+
+The first block of this example is for denying access to Pico's internal files. This is recommend for security reasons, and is included in `.htaccess` for our Apache users.
+
+The second block provides the URL rewriting scheme.
+
+You'll need to adjust the path of `/pico` in this example to match your own Pico installation directory.
+
+Additionally, you'll need to either add `fastcgi_param PICO_URL_REWRITING 1;` to your [PHP location block][NginxPHP] or specify `rewrite_url: true` in your `config.yml`.
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Lighttpd" %}
+
+### Lighttpd
+
+
+
+Pico runs great on Lighttpd. The following config should provide the *bare minimum* configuration you need for Pico.
+
+```
+url.rewrite-once = (
+ "^/pico/(config|content|vendor|composer\.(json|lock|phar))(/|$)" => "/pico/index.php",
+ "^/pico/(.+/)?\.(?!well-known(/|$))" => "/pico/index.php"
+)
+
+url.rewrite-if-not-file = (
+ "^/pico(/|$)" => "/pico/index.php"
+)
+```
+
+The first block of this example is for denying access to Pico's internal files. This is recommend for security reasons, and is included in `.htaccess` for our Apache users.
+
+The second block provides the URL rewriting scheme.
+
+You'll need to adjust the path of `/pico` in this example to match your own Pico installation directory.
+
+Additionally, you'll need to specify `rewrite_url: true` in your `config.yml`.
+
+{% include buttonGroupNav.html mode="end" %}
+{% include buttonGroupNav.html mode="start" id="Caddy" %}
+
+### Caddy
+
+Pico runs great on Caddy. The automatic SSL capabilities of Caddy make it a great choice for your Pico site. The following config should provide the *bare minimum* configuration you need for Pico.
+
+```
+# Caddy Config go here. ;P
+```
+
+
+
+The first block of this example is for denying access to Pico's internal files. This is recommend for security reasons, and is included in `.htaccess` for our Apache users.
+
+The second block provides the URL rewriting scheme.
+
+You'll need to adjust the path of `/pico` in this example to match your own Pico installation directory.
+
+Additionally, you'll need to specify `rewrite_url: true` in your `config.yml`.
+
+
+
+{% include buttonGroupNav.html mode="end" %}
+
+## Configuring Pico
+
+
+
+
+
+Pico is ready to go, right out of the box. However, unless you want your website to be called "Pico", there's at least one configuration option you'll want to set.
+
+Configuring Pico is easy. Start by creating a new file at `config/config.yml`.
+
+Next, take a look at Pico's included `config.yml.template` file for a brief overview of the available settings and their defaults. You'll find this template is pretty well documented [inline][ConfigTemplate], so we won't go into detail about all the options here.
+
+To override a setting, simply copy that line from `config.yml.template` to your new `config.yml` and change the value as desired.
+
+That's it.
+
+
+
+
+### Flexible configuration (Modular configuration?)
+
+Pico is able to load *multiple* config files, giving you extra flexibility.
+
+After loading `config.yml`, Pico will go through the rest of the `config/` folder and load all `.yml` files, in alphabetical order.
+
+Be mindful of this when naming your files though. Once a config option has been set, it *can't* be changed in a later file!
+
+### Security
+
+Since YAML files are plain text files, you should configure your webserver to deny access to the `config/` folder. You wouldn't want your website visitors to be able to read them!
+
+It's not necessarily a security issue, as nothing *confidential* is stored in `config.yml`. However, it's possible that a third party plugin could decide to store sensitive information here.
+
+Overall, it's just a best practice to keep the `config/` folder private. See the [Web Server Configuration][WebServerConfig] section above for instructions specific to your choice of software.
+
+---
+
+## Up Next...
+
+So, we've shown you everything you need to setup Pico on your server. Now it's time for the fun stuff. In the next guide, you'll learn how to create some content. Click through to proceed to the next article.
+
+{: .aligncenter}
+[Creating Content][UpNext]{: .button}
+
+[UpNext]: {{ site.github.url }}/guide/creating-content
+[WebServerConfig]: #web-server-configuration
+
+
+[ModRewrite]: https://httpd.apache.org/docs/current/mod/mod_rewrite.html
+[NginxConfig]: {{ site.github.url }}/in-depth/nginx/
+[NginxPHP]: {{ site.github.url }}/in-depth/nginx/#php-configuration
+[GettingHelp]: {{ site.github.url }}/docs/#getting-help
+[ConfigTemplate]: {{ site.gh_project_url }}/blob/{{ site.gh_project_branch }}/config/config.php.template
+
+
+[Composer]: https://getcomposer.org/
+[LatestRelease]: {{ site.gh_project_url }}/releases/latest
+
+[PicoGit]: {{ site.gh_project_url }}
+[PicoThemeGit]: {{ page.components.PicoTheme }}
+[PicoDeprecatedGit]: {{ page.components.PicoDeprecated }}
+[PicoComposerGit]: {{ page.components.PicoComposer }}
+[Packagist]: https://packagist.org/
+[PicoPackagist]: https://packagist.org/packages/picocms/pico
+[PicoThemePackagist]: https://packagist.org/packages/picocms/pico-theme
+[PicoDeprecatedPackagist]: https://packagist.org/packages/picocms/pico-deprecated
+[PicoComposerPackagist]: https://packagist.org/packages/picocms/pico-composer
+[HelpFork]: https://help.github.com/en/github/getting-started-with-github/fork-a-repo
+
+{% comment %}
+
+---
+---
+
+Here's some quotes from that thread:
+
+ Page Topics
+
+ An "Installing Pico" page that covers, in-depth, the concepts of installing and configuring Pico, your webserver (well, links to external resources anyway) and etc. Everything up until you're looking at Pico's sample content.
+ A "Creating Content" page that goes over YAML and Markdown.
+ Perhaps a general, "Usage" type page that covers things like how URLs work, how to lay out and organize your website, separating content and assets, more about config options, etc.
+ Customization: An in-depth guide to installing community themes, creating your own, understanding Twig, Pico variables, everything. Not plugins though.
+ A separate page for Plugins (and plugin development).
+ Maybe a combination of "Getting Help" and "Contributing" (or "Getting Involved"). It should be a generally community-focused page. On that note, I think it would be great if we eventually had a place for non-development, non-bug related community discussions. I don't want to say a "forum" because that feels like a really outdated notion, but a "place" to develop a community nonetheless.
+
+ Table of Contents
+
+ When on the Overview Page:
+
+ * Installing Pico
+ * Creating Content
+ * Customization
+ * Getting Help
+
+ When on Creating Content Page:
+
+ * Installing Pico
+ * Creating Content
+ * YAML
+ * Markdown
+ * Etc
+ * Customization
+ * Getting Help
+
+* Hmm, [GettingHelp][] is going to be refereed to a LOT... maybe I should write that ahead of time.
+
+{% endcomment %}
\ No newline at end of file
diff --git a/guide/plugins.md b/guide/plugins.md
new file mode 100644
index 00000000..a0d82313
--- /dev/null
+++ b/guide/plugins.md
@@ -0,0 +1,144 @@
+---
+layout: docs
+nav-url: /docs/
+title: The Power of Plugins
+headline: The Power of Plugins
+description: |
+ Pico is incredibly extendable via its Plugin system.
+ Utilizing PHP, you can hook into Pico to create your own custom functionality.
+toc:
+ customization:
+ _title: Customization
+ themes:
+ _title: Themes
+ dealing-with-pages: Dealing with pages
+ twig-filters-and-functions: Twig filters and functions
+ plugins: Plugins
+---
+
+So you've mastered the power offered by Twig and you're still wanting more?
+
+We've got plenty in store for you then. Welcome to the world of Plugins.
+
+## Pre-existing Plugin Problem (lmao)
+
+It's easy to add new functionality to Pico using Plugins. You'll find some plugins listed here in our [Plugins Gallery][], as well as more in our [Plugins Wiki][]. There's a positively *overwhelming* amount of Plugins (and forks of plugins) between these sources. Keep in mind however that most of these were created and developed by community members and not by the Pico Project itself.
+
+At the moment, this split between the website an the Wiki is a bit of a problem. Turns out when you ask users to just edit a wiki themselves... it gets messy fast! In the future, we'd like to get this mess cleaned up a bit.
+
+If you'd like to help with this undertaking, please check out our [Contributing][] Section to learn how to get involved with Pico.
+
+Generally, we're [happy to help][GettingHelp] with any issues you might encounter using these plugins, just remember that we aren't *directly* involved with them. Unfortunately, many of these plugins were contributed once, then forgotten about by developers that moved on. That's not to say they aren't still useful! They just might need a little care to see their full potential.
+
+### Installing Plugins
+
+Plugins are easy to install. Usually, it's as simple as dropping their `.php` file into Pico's `plugins` folder. Depending on the plugin, you may also have to explicitly enable it in `config.yml`. Make sure to read the Plugin's readme though, in case they've included any extra instructions.
+
+Each plugin's readme also likely contains some Twig examples, or other usage information beyond simply *enabling* it.
+
+
+
+#### With Composer
+
+If you're [using Composer][] for your Pico install, you can use it for your plugins too! Simply run the `composer require` command to add a plugin to your project (such as `composer require phrozenbyte/pico-file-prefixes` to add the `pico-file-prefixes` plugin). Using Composer to manage your plugins gives you the same ease of deployment and upgrading that using Composer provides for Pico itself.
+
+At the moment, there's not as many plugins available as Composer packages as we would like to see. If you're a plugin developer, please consider supporting a Composer package in addition to your GitHub repo.
+
+### Older Plugin Support
+
+Thanks to `PicoDeprecated`, Pico's Backwards Compatibility plugin, any plugin written for **Pico 1.0 or later** should still work properly in a modern Pico installation. When attempting to load an older plugin, Pico will automatically enable the `PicoDeprecated` plugin for you as well. There's nothing really to do on your part, older plugins should just *work*. You can however manually *disable* `PicoDeprecated` if you'd like to ensure you're only using plugins that are fully compatible with the current version of Pico. Simply add `PicoDeprecated.enabled: false` to your `config.yml`, and those older plugins won't be loaded anymore.
+
+## Making your own Plugins
+
+So you want to get your hands dirty and write a plugin of your own?
+
+Pico plugins are written in PHP just like Pico itself. You're going to want at least a *basic* understanding of PHP before you continue. Plugins can be simple to develop, but the finer points of coding PHP aren't really something we can cover in this short guide.
+
+As capable as [Theming with Twig][] can be, a PHP-based plugin can offer you a lot more "heavy lifting" when it comes to adding functionality to Pico.
+
+
+
+### Where to Begin?
+
+Don't be a dummy, start with one: the [DummyPlugin][] that is! Pico's Dummy Plugin is a *great* starting place. It contains code stubs for 30 different hook locations! Just choose an appropriate place to hook in your code, and delete the stubs you don't need. Pico will take care of the rest.
+
+To get started, just download a copy of the [DummyPlugin][], place it in the `plugins` folder, and rename it to suit your needs. (Technically, if you want to go digging, you've already got a copy of the DummyPlugin hiding deep inside your `vendor` folder!)
+
+Keep in mind that the name of your plugin's main `.php` file, the name of its folder (if it has one), and the name of its main `class` **much all match!** For the [DummyPlugin][], this means renaming both the `DummyPlugin.php` file *and* its main `DummyPlugin` class (defined in the line `class DummyPlugin extends AbstractPicoPlugin`) to your desired name.
+
+If you're fluent in PHP, you'll notice that the [DummyPlugin][] is *very* well documented. It describes all the possible code hooks and when they get triggered during Pico's execution. It even includes some insight into setting up your plugin, such as setting dependencies and whether your plugin should be loaded by default or not.
+
+You can see this inline documentation rendered as the [phpDocs][] here on our website. The [DummyPlugin Section][DummyPluginPhpDocs] of the phpDocs will cover everything you saw inline, while the main [Pico Section][PicoPhpDocs] might give you more insight into Pico's Core.
+
+[DummyPlugin]: https://github.com/picocms/Pico/blob/master/plugins/DummyPlugin.php
+[phpDocs]: https://picocms.org/phpDoc/
+[DummyPluginPhpDocs]: https://picocms.org/phpDoc/master/classes/DummyPlugin.html
+[PicoPhpDocs]: https://picocms.org/phpDoc/master/classes/Pico.html
+
+
+
+
+
+
+
+
+---
+
+## Up Next...
+
+Surely there will be an up next section *somewhere* at the end of this. It'll have text that goes here.
+
+
+{: .aligncenter}
+[Deconstructing the Defaults][UpNext]{: .button}
+
+[UpNext]: {{ site.github.url }}/guide/deconstructing-the-defaults
+
+{% comment %}
+
+### Plugins
+
+#### Plugins for users
+
+Officially tested plugins can be found at [{{ site.github.url }}/plugins/][OfficialPlugins], but there are many awesome third-party plugins out there! A good start point for discovery is [our Wiki][WikiPlugins].
+
+
+
+
+Pico makes it very easy for you to add new features to your website using plugins. Just like Pico, you can install plugins either using [Composer][] (e.g. `composer require phrozenbyte/pico-file-prefixes`), or manually by uploading the plugin's file (just for small plugins consisting of a single file, e.g. `PicoFilePrefixes.php`) or directory (e.g. `PicoFilePrefixes`) to your `plugins` directory. We always recommend you to use Composer whenever possible, because it makes updating both Pico and your plugins way easier. Anyway, depending on the plugin you want to install, you may have to go through some more steps (e.g. specifying config variables) to make the plugin work. Thus you should always check out the plugin's docs or `README.md` file to learn the necessary steps.
+
+
+
+Plugins which were written to work with Pico 1.0 and later can be enabled and disabled through your `config/config.yml`. If you want to e.g. disable the `PicoDeprecated` plugin, add the following line to your `config/config.yml`: `PicoDeprecated.enabled: false`. To force the plugin to be enabled, replace `false` by `true`.
+
+#### Plugins for developers
+
+You're a plugin developer? We love you guys! You can find tons of information about how to develop plugins at [{{ site.github.url }}/development/][PluginDocs]. If you've developed a plugin before and want to upgrade it to Pico 2.0, refer to the [upgrade section of the docs][PluginUpgrade].
+
+
+
+
+
+
+{% endcomment %}
+
+
+[Twig]: https://twig.sensiolabs.org/documentation
+[UnixTimestamp]: https://en.wikipedia.org/wiki/Unix_timestamp
+[Composer]: https://getcomposer.org/
+[FeaturesHttpParams]: {{ site.github.url }}/in-depth/features/http-params/
+[FeaturesPageTree]: {{ site.github.url }}/in-depth/features/page-tree/
+[FeaturesPagesFunction]: {{ site.github.url }}/in-depth/features/pages-function/
+[PicoTheme]: https://github.com/picocms/pico-theme
+[WikiPlugins]: {{ site.gh_project_url }}/wiki/Pico-Plugins
+[OfficialPlugins]: {{ site.github.url }}/plugins/
+[OfficialThemes]: {{ site.github.url }}/themes/
+[PluginDocs]: {{ site.github.url }}/development/
+[PluginUpgrade]: {{ site.github.url }}/development/#upgrade
diff --git a/guide/theming-with-twig.md b/guide/theming-with-twig.md
new file mode 100644
index 00000000..25b1cbd7
--- /dev/null
+++ b/guide/theming-with-twig.md
@@ -0,0 +1,260 @@
+---
+layout: docs
+nav-url: /docs/
+title: Theming with Twig
+headline: Theming with Twig
+description: |
+ The true power of Pico is in its limitless customization.
+ This guide will help get started with Twig and the endless possibilities it provides.
+toc:
+ pre-existing-possibilities: Pre-existing Possibilities
+ making-pico-your-own:
+ _title: Making Pico Your Own
+ where-to-begin: Where to Begin?
+ other-options: Other Options
+ whats-in-a-theme:
+ _title: What's in a Theme
+ templates: Templates
+ configuring-themes-with-pico-themeyml: Configuring Themes with pico-theme.yml
+ tell-me-about-twig:
+ _title: Tell Me About Twig
+ picos-global-variables:
+ _title: Pico's Global Variables
+ about-urls: About URLs
+ arrays-and-dot-notation: Arrays and Dot Notation
+ escaping: Escaping
+ picos-page-variables:
+ _title: Pico's Page Variables
+ the-pages-function: The pages() Function
+ accessing-specific-pages: Accessing Specific Pages
+ pico-provided-filters: Pico Provided Filters
+---
+
+So, you've had a little taste of Pico and you're wanting more. Now that you know the basics of [Installing Pico][InstallingPico] and [Creating Content][CreatingContent], it's time to take your site to the next level.
+
+## Pre-existing Possibilities
+
+If you haven't seen it yet, there's a link up in the navbar to our [Themes Gallery][Themes]. This gallery consists of *community developed* themes. There are a lot of possibilities here, but keep in mind that these themes were all created and developed by community members and not by the Pico Project itself.
+
+Generally, we're [happy to help][GettingHelp] with any issues you might encounter using these themes, just be aware that we aren't *directly* involved with them. Unfortunately, many of these themes were contributed once, then forgotten about by developers that moved on. That's not to say they aren't still useful! They just might need a little care to see their full potential.
+
+We know that this is a bit of a pain point for new users at the moment, so we're working on curating a set of "Officially Supported" themes for the future.
+
+## Making Pico Your Own
+
+Pico's Themes are generated from [Twig][TwigDocs] Templates. Twig is an *incredibly* powerful templating language developed by [Symfony][].
+
+As you start to explore Twig, you should absolutely check out Twig's [Documentation][TwigDocs]! We just cannot recommend it enough, it's an amazing resource for learning the language.
+
+We're going to start getting our hands dirty at this point, so you'll want at least a *basic* understanding of HTML and CSS before you dig any deeper.
+
+Don't worry, you don't have to be a professional web designer or anything. But for the sake of simplicity, we're going to assume from this point forward that seeing HTML and CSS code won't scare you away.
+
+### Where to Begin?
+
+Whether you're new to Twig or just to Pico, your first stop should be our [Default Theme][PicoTheme]! It's already in your `themes/` folder, and it's also available on [GitHub][PicoTheme].
+
+In Pico, a lot of functionality is left up to the Theme to provide. This allows Pico to be *super* flexible. There's essentially no rules here! You can build your site entirely *your* way. Dream big, anything is possible!
+
+But that flexibility comes at the expense of requiring the theme to do some heavy lifting.
+
+The [Default Theme][PicoTheme] is intentionally simple and straightforward. We'd like it to be something of a "reference implementation" for you. The way functionality is provided in the Default Theme is a good guide for how you should code it yourself.
+
+In fact, the Default Theme can also make a great starting template! Just make a copy of the `themes/default/` folder and get developing. Just don't forget to change your `theme:` in `config.yml` to match the new folder name!
+
+### Other Options
+
+Default Theme not doing it for you? That's fine, it's a little bare-bones of a starting place. There are plenty of Themes in the [Themes Gallery][Themes] you could start from (license permitting).
+
+Also, a little pro-tip: Once you've got a good grasp on theming Pico, it's really easy to convert free HTML templates into proper Pico themes. The web has plenty of these available for many different types of website. Quite a few of the designs in our gallery are actually ports of freely available HTML templates!
+
+## What's in a Theme?
+
+At its most basic, a Pico theme needs two things: an `index.twig` template and a `pico-theme.yml` file to configure it. You'll find many of our themes actually lack `pico-theme.yml`. Don't worry, they're just old, but they'll still be compatible thanks to Pico's ongoing support for backwards compatibility.
+
+### Templates
+
+Your `index.twig` is the main HTML/Twig template that tells Pico how to render your page.
+
+But you're not limited to just the one template. Maybe you want a separate page layout on specific parts of your site? Setting the `Template:` property in the metadata of your page will make it use a separate template. For example, setting `Template: blog` will tell Pico to use `blog.twig` instead.
+
+This isn't the only way to switch layouts either, as Twig is powerful enough that you could code multiple layouts right into `index.twig` with the right logic!
+
+### Configuring Themes with pico-theme.yml
+
+As of Pico 2.0, themes should include a config file named `pico-theme.yml` within their folder. This config file is similar to Pico's `config.yml`. Properties that you set here will also be exposed to your theme as `config.theme_config`, but more on that in a bit.
+
+Here we see the Default Theme's `pico-theme.yml`.
+
+```yml
+api_version: 3 # Use Pico's latest API version for themes
+
+meta: # Register meta headers used by this theme
+ Logo: logo # The URL to your website's logo (value is passed to Pico's "url" Twig filter)
+ Tagline: tagline # Your website's tag line, shown right below your site title (supports Markdown)
+ Social: social # A list of social icons that will be shown in your website's footer;
+ # You must specify a "title", "url" and "icon" per entry
+
+twig_config: # Twig template engine config
+ autoescape: html # Let Twig escape variables by default
+ strict_variables: false # If set to true, Twig will bail out when unset variables are being used
+ charset: utf-8 # The charset used by Twig templates
+
+widescreen: false
+```
+
+- **api_version** - The API Version lets Pico know how to interpret your theme and whether it will need any backwards compatibility features. The current API is version `3`.
+
+- **meta** - If your theme uses additional YML metadata properties in your page headers, you can register them here. Registering a property here allows you to effectively alias a prettier version of it for your users. In this example from the Default Theme, someone can define a `Logo` in their page header, and that gets exposed to Twig as the lowercase `logo`. This can also be a convenient place to document their functions inline for your user, but this is of course optional. We'll go into more details about accessing metadata headers in a bit.
+
+- **twig_config** - Optional configuration to pass to Twig. If you don't specifically have a need to change these, you should just copy the values shown here.
+
+- **Custom Options** - Anything else you define in this file will be available to your theme as `config.theme_config`. You can use the values here to provide some global configuration options to your users. In the Default Theme, setting `widescreen: true` will make the main content area of the page wider. In the Twig template, it does this by attaching an extra, `widescreen`, class to the `body` if this value is set to `true` (and then of course applying some extra CSS styles to it).
+
+## Tell Me About Twig
+
+While you're familiarizing yourself with the [Default Theme][PicoTheme], take a look at Twig's [Documentation][TwigDocs] and the overview page [Twig for Template Designers][TwigDesigners]. Compare some of the syntax in the Overview to the examples within the Default Theme.
+
+Twig is incredibly powerful, so we'll only be covering the *Pico* related bits in this guide. Don't worry though, we'll still have some examples to get you going.
+
+### Pico's Global Variables
+
+As you're building your site, there's going to be a few variables you'll want to use to fill in the blanks. After all, what good would having the same static page for your whole site be?
+
+Use these variables to dynamically populate the content on your page.
+
+
+Global Variable | Description
+----------------|------------
+`{% raw %}{{ site_title }}{% endraw %}` | The title of your website, as defined in `config.yml`.
+`{% raw %}{{ config }}{% endraw %}` | Contains the entirety of your configuration from `config.yml` and other config files. You'll probably use this more for running logic than printing to the page.
+`{% raw %}{{ base_url }}{% endraw %}` | The base URL to your Pico site (eg, `http://example.com`). Pico will try to determine this automatically, but it can be manually set in `config.yml` if needed. Don't use this for links to your content pages, use the [Link filter][Filters] instead.
+`{% raw %}{{ theme_url }}{% endraw %}` | The URL to the currently active theme's folder.
+`{% raw %}{{ assets_url }}{% endraw %}` | The URL to Pico's `assets` folder.
+`{% raw %}{{ themes_url }}{% endraw %}` | The URL to Pico's `themes` folder. Don't confuse this with `theme_url`, this is the folder that *contains* that one.
+`{% raw %}{{ plugins_url }}{% endraw %}` | The URL to Pico's `plugins` folder.
+`{% raw %}{{ version }}{% endraw %}` | Pico's current version string (e.g. `2.0.0`)
+`{% raw %}{{ meta }}{% endraw %}` | Contains the YML Metadata values of the current page.
+`{% raw %}{{ meta.title }}{% endraw %}`{: .table-indent} | The title of the page (from the `Title` YAML header).
+`{% raw %}{{ meta.description }}{% endraw %}`{: .table-indent} | The description of the page (from the `Description` YAML header).
+`{% raw %}{{ meta.author }}{% endraw %}`{: .table-indent} | The author of the page (from the `Author` YAML header).
+`{% raw %}{{ meta.date }}{% endraw %}`{: .table-indent} | The date of the page (from the `Date` YAML header).
+`{% raw %}{{ meta.date_formatted }}{% endraw %}`{: .table-indent} | The formatted date of the page as specified by the `date_format` parameter in your `config.yml`.
+`{% raw %}{{ meta.time }}{% endraw %}`{: .table-indent} | The [Unix timestamp][UnixTimestamp] derived from the `Date` YAML header.
+`{% raw %}{{ meta.robots }}{% endraw %}`{: .table-indent} | The `Robots` YAML header. Used in your theme to fill out the `content` attribute of your `meta` `robots` HTML tag. See the [Default Theme][PicoTheme] for implementation details.
+`{% raw %}{{ content }}{% endraw %}` | The content of the current page after it has been processed through Markdown.
+`{% raw %}{{ previous_page }}{% endraw %}` | The entire data of the previous page, relative to `current_page`.
+`{% raw %}{{ current_page }}{% endraw %}` | The entire data of the current page. See the "Pages" section below for details.
+`{% raw %}{{ next_page }}{% endraw %}` | The entire data of the next page, relative to `current_page`.
+
+#### About URLs
+
+Remember that URLs (e.g. `{% raw %}{{ base_url }}{% endraw %}`) never include a trailing slash `/` so be sure to add one if needed. Also, `theme_url`, `assets_url`, `themes_url`, and `plugins_url` all *contain* `base_url`. You don't need to add it yourself.
+
+Let's use a URL variable. Say you wanted to link to a CSS stylesheet at `themes/my_theme/example.css`. The HTML/Twig for this would read `{% raw %}{% endraw %}`.
+
+#### Arrays and Dot Notation
+
+Some of the variables Pico exposes, such as `config` and `meta` are actually arrays of data and not singular values.
+
+In Twig, we can access these using dot notation. In the list above, you can see this on items like `meta.title`. Twig's dot notation is a shorter way of writing `meta['title']`, or, the item within `meta` named `title`.
+
+This applies to `config` too. Maybe you want a different page layout if pages are ordered alphabetically? Then you could check to see if `config.pages_order_by` was set to `alpha`. Values from your `pico-theme.yml` can also be accessed through `config.theme_config`.
+
+#### Escaping
+
+Keep in mind that Twig automatically escapes all HTML strings by default. This means if you added something like `Tagline: My favorite color` to your page and tried to print it with `{% raw %}{{ meta.tagline }}{% endraw %}`, you'd literally see `My favorite color` on the page (markup and all)!
+
+The recommended way to add formatting like this to your YML is to use Markdown syntax instead and then use Pico's `markdown` filter. This would look like `Tagline: My **favorite** color` and `{% raw %}{{ meta.tagline|markdown(singleLine=true) }}{% endraw %}`. We'll cover the `markdown` filter more when we talk about [Filters][] below.
+
+Another potential solution to this is to use Twig's `raw` filter (eg, `{% raw %}{{ meta.tagline|raw }}{% endraw %}`). Just be aware of the potential security implication when doing so. Using `raw` will allow **any** HTML to be printed to the page as if it were "safe".
+
+The `{% raw %}{{ content }}{% endraw %}` is the only variable that isn't HTML escaped, since it contains the markdown-generated HTML for the page.
+
+### Pico's Page Variables
+
+When using Pico, your markdown `.md` content files are exposed to Twig as an array via the `pages()` function. You can also access their data using the `current_page`, `prev_page`, and, `next_page` variables.
+
+Each page has a number of different variables that you can access using the [Dot Notation][DotNotation] we discussed above.
+
+Page Variable | Description
+--------------|------------
+`{% raw %}{{ id }}{% endraw %}` | The relative path to the content file (which acts as its unique ID).
+`{% raw %}{{ url }}{% endraw %}` | The URL to the page.
+`{% raw %}{{ title }}{% endraw %}` | The title of the page (from the `Title` YAML header).
+`{% raw %}{{ description }}{% endraw %}` | The description of the page (from the `Description` YAML header).
+`{% raw %}{{ author }}{% endraw %}` | The author of the page (from the `Author` YAML header).
+`{% raw %}{{ date }}{% endraw %}` | The date of the page (from the `Date` YAML header).
+`{% raw %}{{ date_formatted }}{% endraw %}` | The formatted date of the page as specified by the `date_format` parameter in your `config.yml`.
+`{% raw %}{{ time }}{% endraw %}` | The [Unix timestamp][UnixTimestamp] derived from the `Date` YAML header.
+`{% raw %}{{ raw_content }}{% endraw %}` | The raw content of a page, not yet processed through Markdown (You can use the [Content filter][Filters] we'll discuss later to access the processed content instead).
+`{% raw %}{{ meta }}{% endraw %}` | The metadata values of the page (see the global `{% raw %}{{ meta }}{% endraw %}` variable above for details).
+`{% raw %}{{ prev_page }}{% endraw %}` | The entire data of the previous page, relative to `current_page`.
+`{% raw %}{{ next_page }}{% endraw %}` | The entire data of the next page, relative to `current_page`.
+`{% raw %}{{ tree_node }}{% endraw %}` | The page's node in Pico's page tree. Usage of this is a rather advanced topic check out Pico's [page tree documentation][FeaturesPageTree] for more details.
+
+#### The pages() Function
+
+The `pages()` function provides powerful depth-control over which pages you're interested in. This allows Pico to always respond lightning-fast when accessing pages.
+
+You may sometimes see older themes access the `pages` variable directly as this used to be the convention in older versions of Pico. While it's still possible to access `pages` in this manner, we won't discuss it here because it's not recommended anymore.
+
+The `pages()` function is a rather exhaustive subject, so it's got its own [in-depth guide][FeaturesPagesFunction] to go into more detail.
+
+By default, `pages()` returns a list of all main pages. This includes top level pages like `content/index.md` and `content/page.md`, but also sub-level indexes like `content/sub/index.md` (but not any of the other pages in `sub/`).
+
+The `pages()` function can also take a few input variables. If you give it a page `id` or folder name (eg `pages("blog")`), it will return only the children of that page on the page tree. So in this example it would return pages like `content/blog/blog-post-1.md`).
+
+Another important `pages()` trick is using `depthOffset=-1` to include the parent page as well. This is commonly used when building page navigation, that way you can include a link to your `index.md`. We'll go over that more when we get to examples though.
+
+#### Accessing Specific Pages
+
+Although the `pages()` function is used whenever you want to access the pages array, *individual* pages can still be accessed through the `pages` variable directly without a performance hit.
+
+Why would you need to access a specific page from within your theme? Plenty of reasons! For example, in Pico's [Default Theme][PicoTheme], a file named `_meta.md` is used to configure your site's `logo`, `tagline`, and `social` media links. This gives the user an easy option to define their configuration right alongside their content.
+
+If you wanted to access the `tagline` from this file, you'd use `{% raw %}{{ pages["_meta"].meta.tagline }}{% endraw %}`. You can access any page this way, by using its page `id` as a selector (inside the square brackets `[ ]`).
+
+Some themes even use the metadata of `index.md` as configuration by accessing it with `{% raw %}{{ pages["index"].meta.property }}{% endraw %}`. Don't forget that page IDs don't include the `.md` from the file name!
+
+### Pico Provided Filters
+
+One of the features that makes [Twig][TwigDocs] so powerful is its ability to Filter data. Twig filters are amazingly flexible with their ability to be piped together. In addition to Twig's built-in filters, Pico includes several of its own filters. Apply these to any variable with an I-bar `|`, just as you would with Twig's own filters.
+
+Filter | Description
+-------|------------
+`link` | Use the `link` filter to create internal links to your content files. This guarantees that will work whether URL rewriting is enabled or not. Just pass a page ID string through the filter to get back its URL (e.g. `{% raw %}{{ "sub/page"|link }}{% endraw %}` might return `https://example.com/pico/?sub/page`).
+`url` | The `url` filter replaces URL placeholders (like `%base_url%`) within strings. This is helpful for when you'd like to use URLs in your metadata headers. For example, if your pages had an `Image:` property, you could set this with `Image: %assets_url%/my_image.png`, then utilize it in your Twig template with `{% raw %}{{ meta.image|url }}{% endraw %}` to have Twig fill out the `assets_url` part for you.
+`content` | You can use the `content` filter to get the markdown processed content of any page. Just pass this filter the page ID string and you're good to go. `{% raw %}{{ "sub/page"|content }}{% endraw %}`.
+`markdown` | The `markdown` filter allows you to process any string as markdown. For example, if you wanted to allow some formatting in your page `Description:`, you could pass it through the markdown filter with `{% raw %}{{ meta.description|markdown }}{% endraw %}`. You can also pass metadata as a parameter to have it replace `%meta.*%` placeholders (so, `{% raw %}{{ "Written by *%meta.author%*"|markdown(meta) }}{% endraw %}` might return "Written by *John Doe*"). Keep in mind that by default, the `markdown` filter returns each paragraph in your content wrapped in paragraph tags ``. If you don't want your output to have these, use the `singleLine` parameter, like this: `{% raw %}{{ "This is a *single* line"|markdown(singleLine=true) }}{% endraw %}`.
+`sort_by` | Arrays can be sorted by their keys using the `sort_by` filter. Let's say you wanted to make some navigation, with your pages appearing in a certain order. You could use `{% raw %}{% for page in pages|sort_by([ 'meta', 'nav' ]) %}...{% endfor %}{% endraw %}` to iterate through all your pages, ordered by their `nav` property. The selector `[ ]` in this example is looking at `page.meta.nav`. By default, items which couldn't be sorted are moved to the bottom of the array. You can change this behavior by specifying `bottom`, `top`, `keep`, or `remove` as a second parameter. Top and bottom are self explanatory, `keep` will keep items in their original order, while `remove` will remove them from the results altogether. So, if you wanted to not include pages that didn't have `nav` set, you could use `pages|sort_by([ 'meta', 'nav' ], remove)`.
+`map` | You can return all values of a given array key using the `map` filter. For example, `{% raw %}{{ pages|map("title") }}{% endraw %}` would return all page titles.
+`url_param` and `form_param` | The `url_param` and `form_param` Twig functions allow you to access HTTP GET and POST values. GET values are query strings passed by url (think of your search terms tacked onto the end of a google url like `?my_search_term=something`), while POST data is sent behind the scenes (like when you submit an HTML form). Using `url_param` and `form_param` allows you to implement features like pagination, tags and categories, dynamic pages, and more - with nothing but Twig! There's an [in-depth guide][FeaturesHttpParams] to this functionality that goes into more detail.
+
+
+---
+
+## Up Next...
+
+There's an awful lot of variables on this page, but how do we use them to build a template? It's probably easier to just *show* you the basics rather than explain them.
+
+On the next page we'll break down the [Default Theme][PicoTheme], going over the basics of what makes it work. A lot of its code will be similar, if not identical, to what you'll need for your own projects. What better way to get you going with Pico than to show you what's already in the box? See you there!
+
+{: .aligncenter}
+[Deconstructing the Defaults][UpNext]{: .button}
+
+[UpNext]: {{ site.github.url }}/guide/deconstructing-the-defaults
+[TwigDocs]: https://twig.symfony.com/doc/1.x/
+[TwigDesigners]: https://twig.symfony.com/doc/1.x/templates.html
+[Symfony]: https://symfony.com
+[InstallingPico]: {{ site.github.url }}/guide/installing
+[CreatingContent]: {{ site.github.url }}/guide/creating-content
+[GettingHelp]: {{ site.github.url }}/guide/getting-help
+[Filters]: #filters
+[DotNotation]: #arrays-and-dot-notation
+[UnixTimestamp]: https://en.wikipedia.org/wiki/Unix_timestamp
+[FeaturesHttpParams]: {{ site.github.url }}/in-depth/features/http-params/
+[FeaturesPageTree]: {{ site.github.url }}/in-depth/features/page-tree/
+[FeaturesPagesFunction]: {{ site.github.url }}/in-depth/features/pages-function/
+[Themes]: {{ site.github.url }}/themes/
+[PicoTheme]: https://github.com/picocms/pico-theme
diff --git a/guide/twig-tips-and-tricks.md b/guide/twig-tips-and-tricks.md
new file mode 100644
index 00000000..1ecac21e
--- /dev/null
+++ b/guide/twig-tips-and-tricks.md
@@ -0,0 +1,21 @@
+---
+layout: docs
+nav-url: /docs/
+title: Twig Tips and Tricks
+headline: Twig Tips and Tricks
+description: |
+ NOT UPDATED YET The true power of Pico is in its limitless customization.
+ This guide will help get started with Twig and the endless theming possibilities Pico provides.
+toc:
+ customization:
+ _title: Customization
+ themes:
+ _title: Themes
+ dealing-with-pages: Dealing with pages
+ twig-filters-and-functions: Twig filters and functions
+ plugins: Plugins
+---
+
+This file was moved to Deconstructing the Defaults. Instead, we're gonna discuss advanced Twig examples here, like the blogging stuff.
+
+Debugging? `{% raw %}{{ page[:-3]|json_encode }}{% endraw %}`? Errors on?
\ No newline at end of file
diff --git a/guide/unused-page-chunks.md b/guide/unused-page-chunks.md
new file mode 100644
index 00000000..679c61c8
--- /dev/null
+++ b/guide/unused-page-chunks.md
@@ -0,0 +1,23 @@
+{% comment %}
+
+# From Theming with Twig
+
+
+
+
+#### Dealing with pages
+
+Pico's `pages()` function is the best way to access all of your site's pages. It uses Pico's page tree to easily traverse a subset of Pico's pages list. It allows you to filter pages and to build recursive menus (like dropdowns). By default, `pages()` returns a list of all main pages (e.g. `content/page.md` and `content/sub/index.md`, but not `content/sub/page.md` or `content/index.md`). If you want to return all pages below a specific folder (e.g. `content/blog/`), pass the folder name as first parameter to the function (e.g. `pages("blog")`). Naturally you can also pass variables to the function. For example, to return a list of all child pages of the current page, use `pages(current_page.id)`. Check out the following code snippet:
+
+{% raw %}
<section class="articles">
+ {% for page in pages(current_page.id) if not page.hidden %}
+ <article>
+ <h2><a href="{{ page.url }}">{{ page.title }}</a></h2>
+ {{ page.id|content }}
+ </article>
+ {% endfor %}
+</section>
{% endraw %}
+
+The `pages()` function is very powerful and also allows you to return not just a page's child pages by passing the `depth` and `depthOffset` params. For example, if you pass `pages(depthOffset=-1)`, the list will also include Pico's main index page (i.e. `content/index.md`). This one is commonly used to create a theme's main navigation. If you want to learn more, head over to Pico's complete [`pages()` function documentation][FeaturesPagesFunction].
+
+{% endcomment %}
\ No newline at end of file
diff --git a/in-depth/features/pages-function.md b/in-depth/features/pages-function.md
index cdd98dfd..702e112b 100644
--- a/in-depth/features/pages-function.md
+++ b/in-depth/features/pages-function.md
@@ -2,8 +2,9 @@
layout: docs
title: Pages Function | Pico Features
headline: Using Pico's `pages()` function
-description: Creating pages with Pico is stupidly simple - but how to access them?
+description: Creating pages with Pico is stupidly simple - but how do you access them?
toc:
+ #old TOC
directory-path-meets-url: Directory path meets URL
picos-page-tree: Pico's page tree
using-picos-pages-function: Using Pico's `pages()` function
@@ -11,8 +12,101 @@ toc:
some-more-things-to-know: Some more things to know
nav-url: /docs/
gh_release: v2.1.0
+galleries:
+ window:
+ style: magnify
+ images:
+ -
+ heading: Pages Function "Window"
+ description: A good way to envision these parameters is as a resizable window around the chosen starting point.
+ fullsize: /style/images/pagesFunctionWindow.png # make real thumbnail?
+ thumbnail: /style/images/pagesFunctionWindow.png # make folder
+ styles: "textalign: center; display: block; margin-left: auto; margin-right: auto;"
+
---
+
+
+
+
+## What is the Pages Function?
+
+Pico sites can sometimes have a LARGE number of pages. The more pages we add, the slower it becomes to iterate over them in our Twig code! Enter the `pages()` function.
+
+Since Pico 2.0, the `pages()` function has replaced our older workflow of directly accessing the `pages` variable. The iconic old `for page in pages` line has evolved to become `for page in pages()`, with those parenthesis `()` being the key to something much greater.
+
+## The breakdown
+
+So, how do we use it? The `pages()` function can take up to four *optional* parameters that let you fine tune the pages you're interested in. Let's take a look.
+
+Parameter | Description
+-------------|------------
+start | The id of the page to start from.
+depth | The maximum depth to select. Use `NULL` to return all descendant pages. Defaults to 0.
+depthOffset | The minimum depth to select pages from. Can be negative. Defaults to 0.
+offset | Start offset by a positive or negative number of levels from the starting page. Defaults to 1, selecting the starting page's children.
+
+A good way to envision these parameters is as a resizable window around the chosen starting point.
+
+{% include gallery.html gallery='window' %}
+
+how many levels deep to go, starting from depthOffset.
+
+
+
+
+
+
+
Creating new pages with Pico definitely is stupidly simple: Simply create a `.md` file in Pico's `content` directory, add a YAML header and some Markdown content and you're good to go to admire your new page in your favorite browser. Navigating to a single page shows the contents of the matching `.md` file in Pico's `content` dir - for example, if you navigate to `https://example.com/pico/sub/page`, you'll see the contents of `content/sub/page.md`. Easy, isn't it? But what if you're creating your own theme and you want to access not just the requested page, but also the contents of any other page. The most basic example is your website's navigation: You surely want some sort of navigation in your theme, right? But how does this work?
## Directory path meets URL
@@ -106,3 +200,24 @@ Anyway, if you really want to learn about the advanced stuff of the `offset` par
[FeaturesPageTree]: {{ site.github.url }}/in-depth/features/page-tree/
[PHPDoc]: {{ site.github.url }}/phpDoc/{{ page.gh_release }}/classes/PicoTwigExtension.html#method_pagesFunction
+
+
+
+{% comment %}
+
+New stuff
+
+
+Think about pages in generations. Let's represent every generation by a single character: A is for index.md, B is for all top-level pages (i.e. contact.md and shop/index.md), C is for all second-level pages (i.e. shop/shipping.md), D is for all third-level-pages (i.e. shop/flowers/daisies.md, shop/flowers/red-roses.md and shop/flowers/tiger-lilies.md). Let's write this as ABCD.
+
+Now think about the pages() function as some sort of "selector", selecting page generations. For example, to create the main menu, you want all pages of the A and B generations (i.e. index.md, contact.md and shop/index.md). Basically you want ABCD, bold meaning that the pages() function shall return all pages in these generations (i.e. the "selected" pages).
+
+The pages() function now returns a given page's children by default, i.e. for shop/index.md (B) it will return shop/shipping.md (ABCD). For index.md (i.e. A) it will return ABCD (i.e. contact.md and shop/index.md), for any page in C it will return ABCD. The depth parameter controls the (right) end of the selector. By passing depth=1 you expand the selector by one generation (depth=2 by two generations, etc.), i.e. depth=1 returns ABCD for any page in B (shop/shipping.md, shop/flowers/daisies.md, shop/flowers/red-roses.md and shop/flowers/tiger-lilies.md for shop/index.md, but none for contact.md!). The depthOffset parameter controls the start (left "end") of the selector. Since our selector must at least be one page generation wide, we can't increase depthOffset without also increasing depth. So, if you pass depth=1 depthOffset=1, depth=1 first expands the selector to two generations, but depthOffset=1 immediately skips the oldest generation in the selector. Thus the function returns ABCD for any page in B.
+
+Let's talk about offset. offset=1 is the default and actually the reason why the pages() function returns a given page's child pages by default. offset moves the whole selector around, both the start and end of it. The default offset=1 moves the selector to ABCD for any page in B, with offset=0 it would rather return ABCD - what makes no sense since it's the given page. By passing offset=2 you move the whole selector to the right, so that ABCD is returned for any page in B. Did you remember that you saw this before? Right, it's the same as depth=1 depthOffset=1. It's not just similar, it is the same! offset works as an shortcut to increase depth and depthOffset with just one parameter.
+
+However, offset is a bit more powerful than depth and depthOffset: It can not just move the selector to the right, but also to the left. If you pass offset=-1 you move the whole selector one generation to the left (offset=-2 by two generations, etc.). This won't work for pages in A, because there's no older generation, but for pages in B. offset=-1 returns ABCD for any page in B. If you want the same for pages in C, use offset=-2. Naturally you can also combine offset and depth: If you want ABCD for pages in C, use offset=-2 depth=1.
+
+Let's get back to our original example: The main menu. How do we create the main menu? We use index.md (i.e. A) as starting point. pages() will return ABCD by default. To also include index.md we pass offset=0. We now get ABCD. To also include the B's, we must also increase depth: offset=0 depth=1 returns the requested ABCD. You remember that offset is a shortcut to both depth and depthOffset? You can achieve exactly the same by passing just depthOffset=-1.
+
+{% endcomment %}
\ No newline at end of file
diff --git a/style/images/pagesFunctionWindow.png b/style/images/pagesFunctionWindow.png
new file mode 100644
index 00000000..f78a2d58
Binary files /dev/null and b/style/images/pagesFunctionWindow.png differ
diff --git a/style/js/buttonGroupNav.js b/style/js/buttonGroupNav.js
new file mode 100644
index 00000000..72c48e09
--- /dev/null
+++ b/style/js/buttonGroupNav.js
@@ -0,0 +1,49 @@
+window.onload = function() {
+ // Get the container element
+ var btnContainers = document.getElementsByClassName("btn-group");
+ var btnSections = document.getElementsByClassName("btn-group-content");
+
+ for (var i = 0; i < btnSections.length; i++) {
+ btnSections[i].classList.add("with_script");
+ };
+
+ for (var i = 0; i < btnContainers.length; i++) {
+ btnContainers[i].classList.add("with_script");
+ // Get all buttons with class="btn" inside the container
+ var btns = btnContainers[i].getElementsByClassName("btn");
+
+ // Set the first btn and section to "active".
+ btns[0].classList.add("active");
+ var section = document.getElementById(btns[0].id.replace("-btn","-section"));
+ section.classList.add("active");
+
+ // Loop through the buttons and add the active class to the current/clicked button
+ for (var j = 0; j < btns.length; j++) {
+ btns[j].addEventListener("click", function() {
+ var current = this.parentNode.getElementsByClassName("btn active");
+ var prev_section = document.getElementById(current[0].id.replace("-btn","-section")); //
+ current[0].classList.remove("active");
+ this.classList.add("active");
+
+ // var prev_section = document.getElementById(current[0].id.replace("-btn","-section"));
+ // console.log("Prev ID is: " + current[0].id.replace("-btn","-section"));
+ prev_section.classList.remove("fade");
+ prev_section.classList.remove("active");
+ var section = document.getElementById(this.id.replace("-btn","-section"));
+ // console.log("Current ID is: " + this.id.replace("-btn","-section"));
+ section.classList.add("fade");
+ setTimeout(function(){
+ section.classList.remove("fade");
+ section.classList.add("active");
+ }, 1); // IMPORTANT!:: 1ms fixes "breakage" from using Timeout, but it'd be better if we just set ALL buttons to off instead of relying on this fragile method of changing only the previous one!
+ });
+ };
+ };
+};
+
+// Probably *not* tolerant of spaces in the id's... (Hasn't broken though...)
+
+// Clean / Change the borrowed comments. Add more of own.
+
+// WHY DOES THE LOOP ONLY RUN ONCE? THERE ARE *TWO* ITEMS! Maybe the script is running twice? (problematically)
+ // Didn't seem to fix it.
\ No newline at end of file
diff --git a/style/js/scripts.js b/style/js/scripts.js
index 77868e40..686ccc5d 100644
--- a/style/js/scripts.js
+++ b/style/js/scripts.js
@@ -1,45 +1,45 @@
/*-----------------------------------------------------------------------------------*/
/* RETINA.JS
-/*-----------------------------------------------------------------------------------*/
-(function () {
- function t(e) {
- this.path = e;
- var t = this.path.split("."),
- n = t.slice(0, t.length - 1).join("."),
- r = t[t.length - 1];
- this.at_2x_path = n + "@2x." + r
- }
- function n(e) {
- this.el = e, this.path = new t(this.el.getAttribute("src"));
- var n = this;
- this.path.check_2x_variant(function (e) {
- e && n.swap()
- })
- }
- var e = typeof exports == "undefined" ? window : exports;
- e.RetinaImagePath = t, t.confirmed_paths = [], t.prototype.is_external = function () {
- return !!this.path.match(/^https?\:/i) && !this.path.match("//" + document.domain)
- }, t.prototype.check_2x_variant = function (e) {
- var n, r = this;
- if (this.is_external()) return e(!1);
- if (this.at_2x_path in t.confirmed_paths) return e(!0);
- n = new XMLHttpRequest, n.open("HEAD", this.at_2x_path), n.onreadystatechange = function () {
- return n.readyState != 4 ? e(!1) : n.status >= 200 && n.status <= 399 ? (t.confirmed_paths.push(r.at_2x_path), e(!0)) : e(!1)
- }, n.send()
- }, e.RetinaImage = n, n.prototype.swap = function (e) {
- function n() {
- t.el.complete ? (t.el.setAttribute("width", t.el.offsetWidth), t.el.setAttribute("height", t.el.offsetHeight), t.el.setAttribute("src", e)) : setTimeout(n, 5)
- }
- typeof e == "undefined" && (e = this.path.at_2x_path);
- var t = this;
- n()
- }, e.devicePixelRatio > 1 && (window.onload = function () {
- var e = document.getElementsByTagName("img"),
- t = [],
- r, i;
- for (r = 0; r < e.length; r++) i = e[r], t.push(new n(i))
- })
-})();
+// /*-----------------------------------------------------------------------------------*/
+// (function () {
+// function t(e) {
+// this.path = e;
+// var t = this.path.split("."),
+// n = t.slice(0, t.length - 1).join("."),
+// r = t[t.length - 1];
+// this.at_2x_path = n + "@2x." + r
+// }
+// function n(e) {
+// this.el = e, this.path = new t(this.el.getAttribute("src"));
+// var n = this;
+// this.path.check_2x_variant(function (e) {
+// e && n.swap()
+// })
+// }
+// var e = typeof exports == "undefined" ? window : exports;
+// e.RetinaImagePath = t, t.confirmed_paths = [], t.prototype.is_external = function () {
+// return !!this.path.match(/^https?\:/i) && !this.path.match("//" + document.domain)
+// }, t.prototype.check_2x_variant = function (e) {
+// var n, r = this;
+// if (this.is_external()) return e(!1);
+// if (this.at_2x_path in t.confirmed_paths) return e(!0);
+// n = new XMLHttpRequest, n.open("HEAD", this.at_2x_path), n.onreadystatechange = function () {
+// return n.readyState != 4 ? e(!1) : n.status >= 200 && n.status <= 399 ? (t.confirmed_paths.push(r.at_2x_path), e(!0)) : e(!1)
+// }, n.send()
+// }, e.RetinaImage = n, n.prototype.swap = function (e) {
+// function n() {
+// t.el.complete ? (t.el.setAttribute("width", t.el.offsetWidth), t.el.setAttribute("height", t.el.offsetHeight), t.el.setAttribute("src", e)) : setTimeout(n, 5)
+// }
+// typeof e == "undefined" && (e = this.path.at_2x_path);
+// var t = this;
+// n()
+// }, e.devicePixelRatio > 1 && (window.onload = function () {
+// var e = document.getElementsByTagName("img"),
+// t = [],
+// r, i;
+// for (r = 0; r < e.length; r++) i = e[r], t.push(new n(i))
+// })
+// })();
/*-----------------------------------------------------------------------------------*/
/* ISOTOPE PORTFOLIO
/*-----------------------------------------------------------------------------------*/
diff --git a/styles.css b/styles.css
new file mode 100644
index 00000000..83ef7966
--- /dev/null
+++ b/styles.css
@@ -0,0 +1,125 @@
+.btn-group {
+ margin-bottom: 20px;
+ display: none;
+ white-space: nowrap;
+ /* Split to second line on shrink, then menu on smallest */
+}
+
+.btn-group.with_script {
+ display: block;
+}
+
+.btn-group .btn {
+ font-weight: 900;
+ font-size: 12px;
+ text-transform: uppercase; /* Might not want this */
+ color: #616161;
+ display: inline-block;
+ background-color: white;
+ border: 1px solid #b9b9b9;
+ padding: 6px 20px;
+ margin: 0;
+/* transition: all 200ms ease-in; */
+ transition: all 200ms ease-in-out 0s;
+ position: relative;
+ cursor: pointer;
+ width: auto;
+ border-radius: 0;
+ text-align: center;
+ letter-spacing: 1px;
+ line-height: 24px;
+/* text-decoration: none; unneeded unless "a" */
+ z-index: 0;
+}
+
+.btn-group .btn:first-of-type {
+ border-radius: 5px 0 0 5px;
+}
+
+.btn-group .btn:last-of-type {
+ border-radius: 0 5px 5px 0;
+}
+
+.btn-group .btn:nth-child(even) {
+ margin: 0 -1px;
+}
+
+.btn-group .btn.active {
+ background-color: #2EAE9B;
+ color: #FFF;
+}
+
+.btn-group .btn:not(.active):hover {
+ border-color: #2EAE9B;
+ color: #2EAE9B;
+ z-index: 10;
+}
+
+/* .btn-group-content {
+
+} */
+
+.btn-group-content.with_script { /* WIP */
+ border-radius: 25px;
+ padding: 36px;
+ padding-bottom: 16px;
+ background-color: #fcfcfc;
+ border: 1px solid #ccc;
+ display: none;
+ opacity: 0;
+ transition: opacity 500ms ease-in-out 0s;
+ margin-bottom: 20px;
+ box-shadow: 2px 2px 5px -2px #b9b9b9;
+ /* box-shadow: 2px 2px 5px #b9b9b9; /* Tweak */
+}
+
+.btn-group-content.active {
+ display: block;
+ opacity: 1;
+}
+
+.btn-group-content.fade {
+ display: block;
+ opacity: 0;
+}
+
+code {
+ /* Test this EVERYWHERE */
+ /* Not bad with Justfy. =D */
+ white-space: nowrap;
+}
+
+.table-indent {
+ margin-left: 1em;
+}
+
+.toc-section { /* WIP */
+ border-radius: 25px;
+ padding: 36px;
+ padding-bottom: 16px;
+ background-color: #fcfcfc;
+ border: 1px solid #ccc;
+ margin-bottom: 20px;
+ box-shadow: 2px 2px 5px -2px #b9b9b9;
+ /* box-shadow: 2px 2px 5px #b9b9b9; /* Tweak */
+}
+
+/* Drop Shadow? */
+
+/*
+
+Notes
+------
+
+SPACING WAS *LITERAL* SPACES IN CODE!
+
+Can we do a `white-space` option on this?
+
+
+
+Needs line-break styles and small view styles (responsive media stuff)
+
+
+Why is the font so BOLD in Firefox? (live)
+
+*/