Merge branch 'master' into next

EXAMPLES.md

@@ -1,18 +1,19 @@
 # Example sites
 
-- [vincent.is](https://vincent.is): https://gitlab.com/Keats/vincent.is
+| Site                                                               |                   Source Code                        |
-- [code<future](http://www.codelessfuture.com/)
+|:-------------------------------------------------------------------|:----------------------------------------------------:|
-- http://t-rex.tileserver.ch (https://github.com/pka/t-rex-website/)
+| [vincent.is](https://vincent.is)                                   | https://gitlab.com/Keats/vincent.is                  |
-- [adrien.is](https://adrien.is): https://github.com/Fandekasp/fandekasp.github.io
+| [code<future](http://www.codelessfuture.com/)                      |                                                      |
-- [Philipp Oppermann's blog](https://os.phil-opp.com/): https://github.com/phil-opp/blog_os/tree/master/blog
+| http://t-rex.tileserver.ch                                         | https://github.com/pka/t-rex-website/                |
-- [seventeencups](https://www.seventeencups.net): https://github.com/17cupsofcoffee/seventeencups.net
+| [Philipp Oppermann's blog](https://os.phil-opp.com/)               | https://github.com/phil-opp/blog_os/tree/master/blog |
-- [j1m.net](https://j1m.net): https://gitlab.com/jwcampbell/j1mnet
+| [seventeencups](https://www.seventeencups.net)                     | https://github.com/17cupsofcoffee/seventeencups.net  |
-- [vaporsoft.net](http://vaporsoft.net): https://github.com/piedoom/vaporsoft
+| [j1m.net](https://j1m.net)                                         | https://gitlab.com/jwcampbell/j1mnet                 |
-- [bharatkalluri.in](https://bharatkalluri.in): https://github.com/BharatKalluri/Blog
+| [vaporsoft.net](http://vaporsoft.net)                              | https://github.com/piedoom/vaporsoft                 |
-- [verpeteren.nl](http://www.verpeteren.nl)
+| [verpeteren.nl](http://www.verpeteren.nl)                          |                                                      |
-- [atlasreports.nl](http://www.atlasreports.nl)
+| [atlasreports.nl](http://www.atlasreports.nl)                      |                                                      |
-- [groksome.com](http://www.groksome.com)
+| [groksome.com](http://www.groksome.com)                            |                                                      |
-- [tuckersiemens.com](https://tuckersiemens.com): https://github.com/reillysiemens/tuckersiemens.com
+| [tuckersiemens.com](https://tuckersiemens.com)                     | https://github.com/reillysiemens/tuckersiemens.com   |
-- [andrei.blue](https://andrei.blue): https://github.com/azah/personal-blog
+| [andrei.blue](https://andrei.blue)                                 | https://github.com/azah/personal-blog                |
-- [Axiomatic Semantics](https://axiomatic.neophilus.net): https://github.com/Libbum/AxiomaticSemantics
+| [Axiomatic Semantics](https://axiomatic.neophilus.net)             | https://github.com/Libbum/AxiomaticSemantics         |
-- [Tinkering](https://tinkering.xyz)
+| [Tinkering](https://tinkering.xyz)                                 |                                                      |
+| [Daniel Sockwell's codesections.com](https://www.codesections.com) | https://gitlab.com/codesections/codesections-website |

docs/content/documentation/content/overview.md

@@ -63,3 +63,42 @@ the public web site. You can achieve this by simply setting `ignored_content` in
 ```
 ignored_content = ["*.xlsx"]
 ```
+
+## Static assets
+
+In addition to placing content files in the `content` directory, you may also place content 
+files in the `static` directory.  Any files/folders that you place in the `static` directory
+will be copied, without modification, to the public directory.  
+
+Typically, you might put site-wide assets (such as the site favicon, site logos or site-wide
+JavaScript) in the root of the static directory.  You can also place any HTML or other files that
+you wish to be included without modification (that is, without being parsed as Markdown files)
+into the static directory. 
+
+Note that the static folder provides an _alternative_ to colocation.  For example, imagine that you
+had the following directory structure (a simplified version of the structure presented above):
+
+```bash
+.
+└── content
+    └── blog
+        ├── configuration
+        │    └── index.md // -> https://mywebsite.com/blog/configuration/
+        └── _index.md // -> https://mywebsite.com/blog/
+```
+
+If you wanted to add an image to the `https://mywebsite.com/blog/configuration` page, you would
+have three options:
+ *  You could save the image to the `content/blog/configuration` folder and then link it with a
+ relative path from the `index.md` page.  This is the approach described under **colocation**,
+ above.
+ *  You could save the image to a `static/blog/configuration` folder and link it in exactly the
+ same way as if you had colocated it.  If you do this, the generated files will be identical to 
+ if you had colocated; the only difference will be that all static files will be saved in the 
+ static folder rather than in the content folder.  Depending on your organizational needs, this
+ may be better or worse.
+ *  Or you could save the image to some arbitrary folder within the static folder.  For example,
+ you could save all images to `static/images`.  Using this approach, you would no longer be able
+ to use relative links, but could use an absolute link to `images/[filename]` to access your 
+ image.  This might be preferable for small sites or for sites that associate images with 
+ multiple pages (e.g., logo images that appear on every page).

docs/content/documentation/deployment/netlify.md

@@ -8,13 +8,16 @@ with no effort. This very site is hosted by Netlify and automatically deployed o
 
 If you don't have an account with Netlify, you can [sign up](https://app.netlify.com) for one.
 
+## Automatic Deploys
 Once you are in the admin interface, you can add a site from a Git provider (GitHub, GitLab or Bitbucket). At the end
  of this process, you can select the deploy settings for the project:
  
- - build command: `GUTENBERG_VERSION=0.3.1 gutenberg build` (replace the version number in the variable by the version you want to use)
+ - build command: `GUTENBERG_VERSION=0.3.3 gutenberg build` (replace the version number in the variable by the version you want to use)
  - publish directory: the path to where the `public` directory is
  
-With this setup, your site should be automatically deployed on every commit on master.
+With this setup, your site should be automatically deployed on every commit on master.  For `GUTENBERG_VERSION`, you may
+use any of the tagged `release` versions in the GitHub repository—Netlify will automatically fetch the tagged version
+and use it to build your site.
 
 However, if you want to use everything that Netlify gives you, you should also publish temporary sites for pull requests.
 
@@ -31,14 +34,33 @@ command = "gutenberg build"
 
 [build.environment]
 # Set the version name that you want to use and Netlify will automatically use it
-GUTENBERG_VERSION = "0.3.1"
+GUTENBERG_VERSION = "0.3.3"
 
 # The magic for deploying previews of branches
-# We need to override the base url with what the url of the preview is ($DEPLOY_PRIME_URL)
+# We need to override the base url with whatever url Netlify assigns to our 
-# otherwise links would not work properly
+# preview site.  We do this using the Netlify environment variable 
+# `$DEPLOY_PRIME_URL`.
+
 [context.deploy-preview]
 command = "gutenberg build --base-url $DEPLOY_PRIME_URL"
 
 ```
 
+## Manual Deploys
+If you would prefer to use a version of Gutenberg that isn't a tagged release (for example, after having built Gutenberg from
+source and made modifications), then you will need to manually deploy your `public` folder to Netlify.  You can do this through
+Netlify's web GUI or via the command line.
 
+For a command-line manual deploy, follow these steps:
+ 1.  Generate a `Personal Access Token` from the settings section of your Netlify account (*not* an OAuth Application)
+ 2.  Build your site with `gutenberg build`
+ 3.  Create a zip folder containing the `public` directory
+ 4.  Run the `curl` command below, filling in your values for PERSONAL_ACCESS_TOKEN_FROM_STEP_1, FILE_NAME.zip and SITE_NAME
+ 5.  (Optional) delete the zip folder
+
+```bash
+curl -H "Content-Type: application/zip" \
+     -H "Authorization: Bearer PERSONAL_ACCESS_TOKEN_FROM_STEP_1" \
+     --data-binary "@FILE_NAME.zip" \
+     https://api.netlify.com/api/v1/sites/SITE_NAME.netlify.com/deploys
+```

docs/content/documentation/templates/overview.md

@@ -10,11 +10,7 @@ As this documentation will only talk about how templates work in Gutenberg, plea
 the [Tera template documentation](https://tera.netlify.com/docs/templates/) if you want
 to learn more about it first.
 
-All templates live in the `templates` directory and built-in or themes templates can
+All templates live in the `templates` directory.  If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it
-be overriden by creating a template with same name in the correct path. For example,
-you can override the RSS template by creating a `templates/rss.xml` file.
-
-If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it
 to print the whole context.
 
 A few variables are available on all templates minus RSS and sitemap:
@@ -23,6 +19,41 @@ A few variables are available on all templates minus RSS and sitemap:
 - `current_path`: the path (full URL without the `base_url`) of the current page, never starting with a `/`
 - `current_url`: the full URL for that page
 
+## Standard Templates
+By default, Gutenberg will look for three templates: `index.html`, which is applied 
+to the site homepage; `section.html`, which is applied to all sections (any HTML 
+page generated by creating a directory within your `content` directory); and 
+`page.html`, which is applied to all pages (any HTML page generated by creating a 
+`.md` file within your `content` directory).
+
+The homepage is always a section (regardless of whether it contains other pages).
+Thus, the `index.html` and `section.html` templates both have access to the 
+section variables.  The `page.html` template has access to the page variables.
+The page and section variables are described in more detail in the next section of this documentation.
+
+## Built-in Templates
+Gutenberg comes with three built-in templates: `rss.xml`, `sitemap.xml`, and 
+`robots.txt` (each described in their own section of this documentation).
+Additionally, themes can add their own templates, which will be applied if not 
+overridden.  You can override built-in or theme templates by creating a template with
+same name in the correct path. For example, you can override the RSS template by
+creating a `templates/rss.xml` file.
+
+## Custom Templates
+In addition to the standard `index.html`, `section.html`, and `page.html` templates,
+you may also create custom templates by creating a `.html` file in the `templates`
+directory.  These custom templates will not be used by default.  Instead, the custom template will _only_ be used if you apply it by setting the `template` front-matter variable to the path for that template (or if you `include` it in another template that is applied).  For example, if you created a custom template for your site's About page called `about.html`, you could apply it to your `about.md` page by including the following front matter in your `about.md` page:
+
+```md
++++
+title = "About Us"
+template = "about.html"
++++
+```
+
+Custom templates are not required to live at the root of your `templates` directory.
+For example, `product_pages/with_pictures.html` is a valid template.
+
 ## Built-in filters
 Gutenberg adds a few filters, in addition of the ones already present in Tera.
 

docs/content/documentation/templates/rss.md

@@ -3,9 +3,12 @@ title = "RSS"
 weight = 50
 +++
 
-Gutenberg will look for a `rss.xml` file in the `templates` directory or 
+If the site `config.toml` file sets `generate_rss = true`, then Gutenberg will 
-use the built-in one. Currently it is only possible to have one RSS feed for the whole
+generate an `rss.xml` page for the site, which will live at `base_url/rss.xml`. To
-site, you cannot create a RSS feed per section or taxonomy.
+generate the `rss.xml` page, Gutenberg will look for a `rss.xml` file in the `templates`
+directory or, if one does not exist, will use the use the built-in rss template.
+Currently it is only possible to have one RSS feed for the whole site; you cannot
+create a RSS feed per section or taxonomy.
 
 **Only pages with a date and that are not draft will be available.**
 

docs/content/themes/after-dark/index.md

@@ -67,4 +67,4 @@ instead.
 ## Original
 This template is based on the Hugo template https://github.com/comfusion/after-dark
 
-        
+        

docs/templates/theme.html

@@ -10,6 +10,9 @@
             <p><b>Author:</b> {{page.extra.author.name}}</p>
             <p><b>License:</b> {{page.extra.license}}</p>
             <p><b>Homepage:</b> <a href="{{page.extra.homepage}}">{{page.extra.homepage}}</a></p>
+            {% if page.extra.live_demo%}
+              <p><b>Live Demo:</b> <a href="{{page.extra.live_demo}}">{{page.extra.live_demo}}</a></p>
+            {% endif %}
             <p><b>Last updated:</b> {{page.extra.updated }}</p>
         </div>
     </div>

snapcraft.yaml

@@ -19,3 +19,7 @@ parts:
   gutenberg:
     plugin: rust
     rust-channel: stable
+    build-packages:
+    - build-essential
+    - cmake
+    - git-core