Merge branch 'master' into next

CONTRIBUTING.md

@@ -30,7 +30,7 @@ $ git submodule update --init
 
 Zola only works with syntaxes in the `.sublime-syntax` format. If your syntax
 is in `.tmLanguage` format, open it in Sublime Text and convert it to `sublime-syntax` by clicking on
-Tools > Developer > New Syntax from ... and put it at the root of `sublime_syntaxes`.
+Tools > Developer > New Syntax from ... and put it in the `sublime/syntaxes` directory.
 
 You can also add a submodule to the repository of the wanted syntax:
 
@@ -56,7 +56,7 @@ $ cargo run --example generate_sublime synpack ../../sublime/syntaxes ../../subl
 
 ### Adding a theme
 A gallery containing lots of themes is located at https://tmtheme-editor.herokuapp.com/#!/editor/theme/Agola%20Dark.
-More themes can be easily added to Zola, just make a PR with the wanted theme added in the `sublime_themes` directory.
+More themes can be easily added to Zola, just make a PR with the wanted theme added in the `sublime/themes` directory.
 
 If you want to test Zola with a new theme, it needs to be built into the syntect file `all.themedump`.
 

EXAMPLES.md

@@ -3,6 +3,7 @@
 | Site                                                               |                   Source Code                            |
 |:-------------------------------------------------------------------|:--------------------------------------------------------:|
 | [vincentprouillet.com](https://www.vincentprouillet.com/)          | https://github.com/Keats/vincentprouillet/               |
+| [blog.williamdes.eu](http://blog.williamdes.eu/)                   | https://github.com/wdesportes/blog.williamdes.eu         |
 | [t-rex.tileserver.ch](https://t-rex.tileserver.ch)                 | https://github.com/t-rex-tileserver/t-rex-website/       |
 | [Philipp Oppermann's blog](https://os.phil-opp.com/)               | https://github.com/phil-opp/blog_os/tree/master/blog     |
 | [seventeencups](https://www.seventeencups.net)                     | https://github.com/17cupsofcoffee/seventeencups.net      |

README.md

@@ -33,6 +33,7 @@ in the `docs/content` folder of the repository and the community can use [its fo
 | LiveReload                      | ![yes] | ![no]  | ![yes] | ![yes]  |
 | Netlify support                 | ![yes] | ![no]  | ![yes] | ![no]   |
 | Vercel support                  | ![yes] | ![no]  | ![yes] | ![yes]  |
+| Cloudflare Pages support        | ![yes] | ![no]  | ![yes] | ![yes]  |
 | Breadcrumbs                     | ![yes] | ![no]  | ![no]  | ![yes]  |
 | Custom output formats           | ![no]  | ![no]  | ![yes] | ![no]   |
 

docs/content/documentation/content/page.md

@@ -10,10 +10,10 @@ If a file ending with `.md` is named `index.md`, it will generate a page
 with the name of its directory (for example, `/content/about/index.md` would
 create a page at `[base_url]/about`). (Note the lack of an underscore; if the file
 were named `_index.md`, then it would create a **section** at `[base_url]/about`, as
-discussed in a previous part of this documentation.  In contrast, naming the file `index.md` will
+discussed in a previous part of this documentation. In contrast, naming the file `index.md` will
 create a **page** at `[base_url]/about`).
 
-If the file is given any name *other* than `index.md` or `_index.md`, then it will
+If the file is given any name _other_ than `index.md` or `_index.md`, then it will
 create a page with that name (without the `.md`). For example, naming a file in the root of your
 content directory `about.md` would create a page at `[base_url]/about`.
 Another exception to this rule is that a filename starting with a datetime (YYYY-mm-dd or [an RFC3339 datetime](https://www.ietf.org/rfc/rfc3339.txt)) followed by
@@ -23,7 +23,7 @@ be available at `[base_url]/hello-world`. Note that the full RFC3339 datetime co
 character in a filename on Windows.
 
 As you can see, creating an `about.md` file is equivalent to creating an
-`about/index.md` file.  The only difference between the two methods is that creating
+`about/index.md` file. The only difference between the two methods is that creating
 the `about` directory allows you to use asset co-location, as discussed in the
 [overview](@/documentation/content/overview.md#asset-colocation) section.
 
@@ -35,7 +35,7 @@ For any page within your content folder, its output path will be defined by eith
 - its filename
 
 Either way, these proposed path will be sanitized before being used.
-If `slugify.paths` is set to `"on"` in the site's config - the default - paths are [slugified](https://en.wikipedia.org/wiki/Clean_URL#Slug). 
+If `slugify.paths` is set to `"on"` in the site's config - the default - paths are [slugified](https://en.wikipedia.org/wiki/Clean_URL#Slug).
 If it is set to `"safe"`, only sanitation is performed, with the following characters being removed: `<`, `>`, `:`, `/`, `|`, `?`, `*`, `#`, `\\`, `(`, `)`, `[`, `]` as well as newlines and tabulations. This ensures that the path can be represented on all operating systems.
 Additionally, trailing whitespace and dots are removed and whitespaces are replaced by `_`.
 
@@ -62,6 +62,7 @@ This frontmatter will output the article to `[base_url]/zines/femmes-libres-lib
 ### Path from filename
 
 When the article's output path is not specified in the frontmatter, it is extracted from the file's path in the content folder. Consider a file `content/foo/bar/thing.md`. The output path is constructed:
+
 - if the filename is `index.md`, its parent folder name (`bar`) is used as output path
 - otherwise, the output path is extracted from `thing` (the filename without the `.md` extension)
 
@@ -109,7 +110,7 @@ weight = 0
 # A draft page is only loaded if the `--drafts` flag is passed to `zola build`, `zola serve` or `zola check`.
 draft = false
 
-# If set, this slug will be instead of the filename to make the URL.
+# If set, this slug will be used instead of the filename to make the URL.
 # The section path will still be used.
 slug = ""
 
@@ -148,7 +149,7 @@ paragraph of the page content in a list.
 To do so, add <code>&lt;!-- more --&gt;</code> in your content at the point
 where you want the summary to end. The content up to that point will be
 available separately in the
-[template](@/documentation/templates/pages-sections.md#page-variables).
+[template](@/documentation/templates/pages-sections.md#page-variables) via `page.summary`.
 
 A span element in this position with a `continue-reading` id is created, so you can link directly to it if needed. For example:
 `<a href="{{ page.permalink }}#continue-reading">Continue Reading</a>`.

docs/content/documentation/content/sass.md

@@ -8,7 +8,7 @@ maintenance of large sets of CSS rules. If you're curious about what Sass
 is and why it might be useful for styling your static site, the following links
 may be of interest:
 
-* The [official Sass website](http://sass-lang.com/)
+* The [official Sass website](https://sass-lang.com/)
 * [Why Sass?](https://alistapart.com/article/why-sass), by Dan Cederholm
 
 ## Using Sass in Zola

docs/content/documentation/content/search.md

@@ -22,5 +22,5 @@ the JavaScript/CSS code to do an actual search and display results. You can look
 implements it to get an idea: [search.js](https://github.com/getzola/zola/tree/master/docs/static/search.js).
 
 ## Configuring the search index
-In some cases, the default indexing strategy is not suitable. You can customise which fields to include and whether
+In some cases, the default indexing strategy is not suitable. You can customize which fields to include and whether
 to truncate the content in the [search configuration](@/documentation/getting-started/configuration.md).

docs/content/documentation/content/section.md

@@ -7,7 +7,7 @@ A section is created whenever a directory (or subdirectory) in the `content` sec
 `_index.md` file.  If a directory does not contain an `_index.md` file, no section will be
 created, but Markdown files within that directory will still create pages (known as orphan pages).
 
-The index page (i.e., the page displayed when a user browses to your `base_url`) is a section,
+The homepage (i.e., the page displayed when a user browses to your `base_url`) is a section,
 which is created whether or not you add an `_index.md` file at the root of your `content` directory.
 If you do not create an `_index.md` file in your content directory, this main content section will
 not have any content or metadata.  If you would like to add content or metadata, you can add an
@@ -73,6 +73,9 @@ paginate_by = 0
 # The default is page/1.
 paginate_path = "page"
 
+# If set, there will pagination will happen in a reversed order.
+paginate_reversed = false
+
 # This determines whether to insert a link for each header like the ones you can see on this site if you hover over
 # a header.
 # The default template can be overridden by creating an `anchor-link.html` file in the `templates` directory.
@@ -208,4 +211,4 @@ equally weighted sections. Thus, if the `weight` variable for your section is no
 is set in a way that produces ties), then your sections will be sorted in
 **random** order. Moreover, that order is determined at build time and will
 change with each site rebuild.  Thus, if there is any chance that you will
-iterate over your sections, you should always assign them a weight.
+iterate over your sections, you should always assign them distinct weights.

docs/content/documentation/content/shortcodes.md

@@ -10,7 +10,7 @@ try [Tera macros](https://tera.netlify.com/docs#macros).
 
 Broadly speaking, Zola's shortcodes cover two distinct use cases:
 
-* Inject more complex HTML: Markdown is good for writing, but it isn't great when you need add inline HTML or styling.
+* Inject more complex HTML: Markdown is good for writing, but it isn't great when you need to add inline HTML or styling.
 * Ease repetitive data based tasks: when you have [external data](@/documentation/templates/overview.md#load-data) that you
   want to display in your page's body.
 
@@ -59,7 +59,7 @@ This will create a shortcode `books` with the argument `path` pointing to a `.to
 titles and descriptions. They will flow with the rest of the document in which `books` is called.
 
 Shortcodes are rendered before the page's Markdown is parsed so they don't have access to the page's table of contents.
-Because of that, you also cannot use the `get_page`/`get_section`/`get_taxonomy` global functions. It might work while
+Because of that, you also cannot use the [`get_page`](@/documentation/templates/overview.md#get-page)/[`get_section`](@/documentation/templates/overview.md#get-section)/[`get_taxonomy`](@/documentation/templates/overview.md#get-taxonomy) global functions. It might work while
 running `zola serve` because it has been loaded but it will fail during `zola build`.
 
 ## Using shortcodes

docs/content/documentation/content/table-of-contents.md

@@ -12,22 +12,24 @@ documentation for information on its structure.
 Here is an example of using that field to render a two-level table of contents:
 
 ```jinja2
-<ul>
-{% for h1 in page.toc %}
-    <li>
-        <a href="{{h1.permalink | safe}}">{{ h1.title }}</a>
-        {% if h1.children %}
-            <ul>
-                {% for h2 in h1.children %}
-                    <li>
-                        <a href="{{h2.permalink | safe}}">{{ h2.title }}</a>
-                    </li>
-                {% endfor %}
-            </ul>
-        {% endif %}
-    </li>
-{% endfor %}
-</ul>
+{% if page.toc %}
+    <ul>
+    {% for h1 in page.toc %}
+        <li>
+            <a href="{{h1.permalink | safe}}">{{ h1.title }}</a>
+            {% if h1.children %}
+                <ul>
+                    {% for h2 in h1.children %}
+                        <li>
+                            <a href="{{h2.permalink | safe}}">{{ h2.title }}</a>
+                        </li>
+                    {% endfor %}
+                </ul>
+            {% endif %}
+        </li>
+    {% endfor %}
+    </ul>
+{% endif %}
 ```
 
 While headers are neatly ordered in this example, it will work just as well with disjoint headers.

docs/content/documentation/deployment/cloudflare-pages.md

@@ -0,0 +1,22 @@
++++
+title = "Cloudflare Pages"
+weight = 60
++++
+
+Cloudflare is a cloud solutions provider with a huge proprietary content delivery network. Like Netlify or Vercel Cloudflare Pages makes deployment process flexible and easy. You can add GitHub repo to the service and build&host Zola-bases websites after each PR automatically. 
+
+## Step-by-step
+
+1. Open or create the new one Cloudflare account and choice Pages on the right nav column
+2. Press the button _"Create a project"_
+3. Select the GitHub repo that contains your Zola website and connect it to Cloudflare Pages
+4. Click _"Begin setup"_
+5. Enter your project name and keep in mind, if you would like to use default Pages domain (pages.dev) it will be your website future URL, like `yourprojectname.pages.dev`. Also, select a production branch.
+6. In _Build settings_ select Zola as a _Framework preset_. _Build command_ and _Build output directory_ will be filled automatically. 
+7. Toggle _Environment variables_ below and add `ZOLA_VERSION` as _a variable name_ and `0.13.0` or an actual Zola's version as a _value_.
+8. Save and deploy.
+
+Your website is now built and deployed to Pages. You may add custom domain or change some settings in the Pages dashboard.
+
+Also, you may find well documented settings and howto [Getting started with Cloudflare Pages](https://developers.cloudflare.com/pages/getting-started) and
+[Deloying Zola with Cloudflare Pages](https://developers.cloudflare.com/pages/how-to/deploy-a-zola-site#deploying-with-cloudflare-pages) in Developers portal. 

docs/content/documentation/deployment/github-pages.md

@@ -6,13 +6,22 @@ weight = 30
 By default, GitHub Pages uses Jekyll (a ruby based static site generator),
 but you can also publish any generated files provided you have an `index.html` file in the root of a branch called
 `gh-pages` or `master`. In addition you can publish from a `docs` directory in your repository. That branch name can
-also be manually changed in the settings of a repository.
+also be manually changed in the settings of a repository. To serve a site at `<username>.github.io` or
+`<organization>.github.io`, you must name the repository `<username>.github.io` or
+`<organization>.github.io` (otherwise GitHub will append the repository name to the URL, e.g.:
+`<username>.github.io/<repositoryname>`.
 
 We can use any continuous integration (CI) server to build and deploy our site. For example:
 
  * [Github Actions](#github-actions)
  * [Travis CI](#travis-ci)
 
+In either case, it seems to work best if you use `git submodule` to include your theme, e.g.:
+
+```shell
+git submodule add https://github.com/getzola/after-dark.git themes/after-dark
+```
+
 ## Github Actions
 
 Using *Github Actions* for the deployment of your Zola-Page on Github-Pages is pretty easy. You basically need three things:
@@ -33,32 +42,65 @@ on: push
 name: Build and deploy GH Pages
 jobs:
   build:
-    name: shalzz/zola-deploy-action
     runs-on: ubuntu-latest
     steps:
-    # Checkout
-    - uses: actions/checkout@master
-    # Build & deploy
-    - name: shalzz/zola-deploy-action
-      uses: shalzz/[email protected]
-      env:
-        # Target branch
-        PAGES_BRANCH: gh-pages
-        # Provide personal access token
-        TOKEN: ${{ secrets.TOKEN }}
+      - name: checkout
+        uses: actions/checkout@v2
+      - name: build_and_deploy
+        uses: shalzz/[email protected]
+        env:
+          # Target branch
+          PAGES_BRANCH: gh-pages
+          # Provide personal access token
+          TOKEN: ${{ secrets.TOKEN }}
 ```
 
 This script is pretty simple, because the [zola-deploy-action](https://github.com/shalzz/zola-deploy-action) is doing everything for you. You just need to provide some details. For more configuration options check out the [README](https://github.com/shalzz/zola-deploy-action/blob/master/README.md).
 
-By commiting the action your first build is triggered. Wait until it's finished, then you should see in your repository a new branch *gh-pages* with the compiled *Zola* page in it.
+By committing the action your first build is triggered. Wait until it's finished, then you should see in your repository a new branch *gh-pages* with the compiled *Zola* page in it.
 
 Finally we need to check the *Github Pages* section of the repository settings. Click on the *Settings* tab and scroll down to the *Github Pages* section. Check if the source is set to *gh-pages* branch and the directory is */ (root)*. You should also see your *Github Pages* link.
 
-There you can also configure a *custom domain* and *Enforce HTTPS* mode. Before configuring a *custom domains*, please check out [this](https://github.com/shalzz/zola-deploy-action/blob/master/README.md#custom-domain). 
+There you can also configure a *custom domain* and *Enforce HTTPS* mode. Before configuring a *custom domains*, please check out [this](https://github.com/shalzz/zola-deploy-action/blob/master/README.md#custom-domain).
+
+If you want to keep the source of your site in a private repository (including, for example, draft
+posts), adapt the following `.github/workflows/main.yml`:
+
+```yaml
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/main'
+    steps:
+      - name: 'checkout'
+        uses: actions/checkout@v2
+      - name: 'build'
+        uses: shalzz/[email protected]
+        env:
+          PAGES_BRANCH: gh-pages
+          BUILD_DIR: .
+          TOKEN: ${{ secrets.TOKEN }}
+          # BUILD_ONLY: true
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: 'checkout'
+        uses: actions/checkout@v2
+      - name: 'build and deploy'
+        uses: shalzz/[email protected]
+        env:
+          PAGES_BRANCH: master
+          BUILD_DIR: .
+          TOKEN: ${{ secrets.PUBLIC_TOKEN }}
+          REPOSITORY: username/username.github.io
+```
+by substituting your username or organization.
 
 ## Travis CI
 
-We are going to use [Travis CI](https://travis-ci.org) to automatically publish the site. If you are not using Travis
+Alternatively, you can use [Travis CI](https://www.travis-ci.com/) to automatically publish the site. If you are not using Travis
 already, you will need to login with the GitHub OAuth and activate Travis for the repository.
 Don't forget to also check if your repository allows GitHub Pages in its settings.
 
@@ -72,7 +114,7 @@ submodules. When doing this, ensure that you are using the `https` version of th
 $ git submodule add {THEME_URL} themes/{THEME_NAME}
 ```
 
-## Allowing Travis to push to GitHub
+### Allowing Travis to push to GitHub
 
 Before pushing anything, Travis needs a Github private access key to make changes to your repository.
 If you're already logged in to your account, just click [here](https://github.com/settings/tokens) to go to
@@ -86,7 +128,7 @@ Copy it into your clipboard and head back to Travis.
 Once on Travis, click on your project, and navigate to "Settings". Scroll down to "Environment Variables" and input a name of `GH_TOKEN` with a value of your access token.
 Make sure that "Display value in build log" is off, and then click add. Now Travis has access to your repository.
 
-## Setting up Travis
+### Setting up Travis
 
 We're almost done. We just need some scripts in a .travis.yml file to tell Travis what to do.
 
@@ -98,7 +140,7 @@ language: minimal
 before_script:
   # Download and unzip the zola executable
   # Replace the version numbers in the URL by the version you want to use
-  - curl -s -L https://github.com/getzola/zola/releases/download/v0.9.0/zola-v0.9.0-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin
+  - curl -s -L https://github.com/getzola/zola/releases/download/v0.13.0/zola-v0.13.0-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin
 
 script:
   - zola build
@@ -117,4 +159,4 @@ after_success: |
 If your site is using a custom domain, you will need to mention it in the `ghp-import` command:
 `ghp-import -c vaporsoft.net -n public` for example.
 
-Credits: this page is based on the article https://vaporsoft.net/publishing-gutenberg-to-github/
+Credits: The Travis-CI section of this page is based on the article https://vaporsoft.net/publishing-gutenberg-to-github/