Add comments to pico-theme.yml and mention it in README.md

README.md

@@ -40,7 +40,7 @@ Anyway, since Pico's default theme is meant to be a starting point for your own
 
 ```yaml
 ---
-social:
+Social:
     - title: Visit us on GitHub
       url: https://github.com/picocms/Pico
       icon: octocat
@@ -50,6 +50,8 @@ social:
 ---
 ```
 
+You should also check out the theme's `pico-theme.yml`: First of all it tells Pico to use the latest API version for themes and adjusts Pico's default Twig config. But more importantly it also registers the mentioned `widescreen` theme config as well as the meta header `Social`.
+
 Getting Help
 ------------
 

pico-theme.yml

@@ -1,11 +1,12 @@
-api_version: 3
+api_version: 3                  # Use Pico's latest API version for themes
 
-meta:
-    Social: social
+meta:                           # Register meta headers used by this theme
+    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:
-    autoescape: html
-    strict_variables: false
-    charset: utf-8
+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               # Use more horicontal space (i.e. make the site container wider)