docs: fix order of events in zola overview (templates, server, content)

Author: iamorphen

docs/content/documentation/getting-started/installation.md

@@ -175,7 +175,7 @@ jobs:
     steps:
       - uses: taiki-e/install-action@v2
         with:
-          tool: zola@0.17.1
+          tool: zola@0.19.1
       # ...
 ```
 
@@ -187,34 +187,34 @@ Zola is available on [the GitHub registry](https://github.com/getzola/zola/pkgs/
 It has no `latest` tag, you will need to specify a [specific version to pull](https://github.com/getzola/zola/pkgs/container/zola/versions).
 
 ```sh
-$ docker pull ghcr.io/getzola/zola:v0.17.1
+$ docker pull ghcr.io/getzola/zola:v0.19.1
 ```
 
 #### Build
 
 ```sh
-$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app ghcr.io/getzola/zola:v0.17.1 build
+$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app ghcr.io/getzola/zola:v0.19.1 build
 ```
 
 #### Serve
 
 ```sh
-$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 ghcr.io/getzola/zola:v0.17.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost
+$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 ghcr.io/getzola/zola:v0.19.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost
 ```
 
 You can now browse http://localhost:8080.
 
 > To enable live browser reload, you may have to bind to port 1024. Zola searches for an open
 > port between 1024 and 9000 for live reload. The new docker command would be
-> `$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 -p 1024:1024 ghcr.io/getzola/zola:v0.17.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost`
+> `$ docker run -u "$(id -u):$(id -g)" -v $PWD:/app --workdir /app -p 8080:8080 -p 1024:1024 ghcr.io/getzola/zola:v0.19.1 serve --interface 0.0.0.0 --port 8080 --base-url localhost`
 
 #### Multi-stage build
 
 Since there is no shell in the Zola docker image, if you want to use it from inside a Dockerfile, you have to use the
 exec form of `RUN`, like:
 
 ```Dockerfile
-FROM ghcr.io/getzola/zola:v0.17.1 as zola
+FROM ghcr.io/getzola/zola:v0.19.1 as zola
 
 COPY . /project
 WORKDIR /project

docs/content/documentation/getting-started/overview.md

@@ -19,11 +19,11 @@ Unlike some SSGs, Zola makes no assumptions regarding the structure of your site
 
 ### Initialize Site
 
-> This overview is based on Zola 0.17.1.
+> This overview is based on Zola 0.19.1.
 
 Please see the detailed [installation instructions for your platform](@/documentation/getting-started/installation.md). With Zola installed, let's initialize our site:
 
-```bash
+```
 $ zola init myblog
 ```
 
@@ -38,7 +38,7 @@ You will be asked a few questions.
 
  For our blog, let's accept the default values (i.e., press Enter for each question). We now have a `myblog` directory with the following structure:
 
-```bash
+```
 ├── config.toml
 ├── content
 ├── sass
@@ -66,28 +66,15 @@ For reference, by the **end** of this overview, our `myblog` directory will have
 └── themes/
 ```
 
-Let's start the Zola development server within the newly created `myblog` directory:
+Change directory into the newly-created `myblog` directory.
 
-```bash
-$ cd myblog
-$ zola serve
-Building site...
-Checking all internal links with anchors.
-> Successfully checked 0 internal link(s) with anchors.
--> Creating 0 pages (0 orphan) and 0 sections
-Done in 13ms.
-
-Listening for changes in .../myblog/{config.toml,content,sass,static,templates}
-Press Ctrl+C to stop
-
-Web server is available at http://127.0.0.1:1111
-```
+### Templates
 
-If you point your web browser to <http://127.0.0.1:1111>, you should see a "Welcome to Zola" message.
+We'll first create some templates to describe the structure of our site.
 
-### Home Page
+#### Home Page Template
 
-Let's make a home page. To do this, let's first create a `base.html` file inside the `templates` directory. This step will make more sense as we move through this overview.
+Let's make a template for a home page. Create `templates/base.html` with the following content. This step will make more sense as we move through this overview.
 
 ```html
 <!DOCTYPE html>
@@ -109,7 +96,7 @@ Let's make a home page. To do this, let's first create a `base.html` file inside
 </html>
 ```  
 
-Now, let's create an `index.html` file inside the `templates` directory.
+Now, let's create `templates/index.html` with the following content.
 
 ```html
 {% extends "base.html" %}
@@ -123,38 +110,9 @@ Now, let's create an `index.html` file inside the `templates` directory.
 
 This tells Zola that `index.html` extends our `base.html` file and replaces the block called "content" with the text between the `{% block content %}` and `{% endblock content %}` tags.
 
-### Content Directory
-
-Now let's add some content. We'll start by making a `blog` subdirectory in the `content` directory and creating an `_index.md` file inside it. This file tells Zola that `blog` is a [section](@/documentation/content/section.md), which is how content is categorized in Zola.
-
-```bash
-├── content
-│   └── blog
-│       └── _index.md
-```
+#### Blog Template
 
-In the `_index.md` file, we'll set the following variables in [TOML](https://github.com/toml-lang/toml) format:
-
-```md
-+++
-title = "List of blog posts"
-sort_by = "date"
-template = "blog.html"
-page_template = "blog-page.html"
-+++
-```
-
-> Note that although no variables are mandatory, the opening and closing `+++` are required.
-
-* *sort_by = "date"* tells Zola to use the date to order our section pages (more on pages below). 
-* *template = "blog.html"* tells Zola to use `blog.html` in the `templates` directory as the template for listing the Markdown files in this section. 
-* *page_template = "blog-page.html"* tells Zola to use `blog-page.html` in the `templates` directory as the template for individual Markdown files. 
-
-For a full list of section variables, please see the [section](@/documentation/content/section.md) documentation. We will use *title = "List of blog posts"* in a template (see below).
-
-### Templates
-
-Let's now create some more templates. In the `templates` directory, create a `blog.html` file with the following contents:
+To create a template for a page that lists all blog posts, create `templates/blog.html` with the following content.
 
 ```html
 {% extends "base.html" %}
@@ -164,34 +122,20 @@ Let's now create some more templates. In the `templates` directory, create a `bl
   {{ section.title }}
 </h1>
 <ul>
-  <!-- If you are using pagination, section.pages will be empty. You need to use the paginator object -->  
+  <!-- If you are using pagination, section.pages will be empty.
+       You need to use the paginator object -->  
   {% for page in section.pages %}
   <li><a href="{{ page.permalink | safe }}">{{ page.title }}</a></li>
   {% endfor %}
 </ul>
 {% endblock content %}
 ```
 
-As done by `index.html`, `blog.html` extends `base.html`, but this time we want to list the blog posts. The *title* we set in the `_index.md` file above is available to us as `{{ section.title }}`. In the list below the title, we loop through all the pages in our section (`blog` directory) and output the page title and URL using `{{ page.title }}` and `{{ page.permalink | safe }}`, respectively. We use the `| safe` filter because the permalink doesn't need to be HTML escaped (escaping would cause `/` to render as `&#x2F;`).
-
-If you go to <http://127.0.0.1:1111/blog/>, you will see the section page for `blog`. The list is empty because we don't have any blog posts. Let's fix that now.
+As done by `index.html`, `blog.html` extends `base.html`, but in this template we want to list the blog posts. Here we also see expressions such as `{{ section.[...] }}` and `{{ page.[...] }}` which will be replaced with values from our [content](#content) when zola combines content with this template to render a page. In the list below the header, we loop through all the pages in our section (`blog` directory; more on this when we create content) and output each page title and URL using `{{ page.title }}` and `{{ page.permalink | safe }}`, respectively. We use the `| safe` filter because the permalink doesn't need to be HTML escaped (escaping would cause `/` to render as `&#x2F;`).
 
-### Markdown Content
+#### Blog Post Template
 
-In the `blog` directory, create a file called `first.md` with the following contents:
-
-```md
-+++
-title = "My first post"
-date = 2019-11-27
-+++
-
-This is my first blog post.
-```
-
-The *title* and *date* will be available to us in the `blog-page.html` template as `{{ page.title }}` and `{{ page.date }}`, respectively. All text below the closing `+++` will be available to us as `{{ page.content }}`.
-
-We now need to make the `blog-page.html` template. In the `templates` directory, create this file with the contents:
+We have templates describing our home page and a page that lists all blog posts. Let's now create a template for an individual blog post. Create `templates/blog-page.html` with the following content.
 
 ```html
 {% extends "base.html" %}
@@ -207,7 +151,73 @@ We now need to make the `blog-page.html` template. In the `templates` directory,
 
 > Note the `| safe` filter for `{{ page.content }}`.
 
-This should start to look familiar. If you now go back to our blog list page at <http://127.0.0.1:1111/blog/>, you should see our lonely post. Let's add another. In the `content/blog` directory, let's create the file `second.md` with the contents:
+### Zola Live Reloading
+
+Now that we've outlined our site's structure, let's start the Zola development server in the `myblog` directory.
+
+```
+$ zola serve
+Building site...
+Checking all internal links with anchors.
+> Successfully checked 0 internal link(s) with anchors.
+-> Creating 0 pages (0 orphan) and 0 sections
+Done in 13ms.
+
+Web server is available at http://127.0.0.1:1111
+
+Listening for changes in .../myblog/{config.toml,content,sass,static,templates}
+Press Ctrl+C to stop
+```
+
+If you point your web browser to <http://127.0.0.1:1111>, you will see a message saying, "This is my blog made with Zola."
+
+If you go to <http://127.0.0.1:1111/blog/>, you will currently get a 404 which we will fix next.
+
+### Content
+
+We'll now create some content that Zola will use to generate site pages based on our templates.
+
+#### Sections
+
+We'll start by creating `content/blog/_index.md`. This file tells Zola that `blog` is a [section](@/documentation/content/section.md), which is how content is categorized in Zola. In the `_index.md` file, we'll set the following variables in [TOML](https://github.com/toml-lang/toml) format:
+
+```md
++++
+title = "List of blog posts"
+sort_by = "date"
+template = "blog.html"
+page_template = "blog-page.html"
++++
+```
+
+> Note that although no variables are mandatory, the opening and closing `+++` are required.
+
+* *sort_by = "date"* tells Zola to use the date to order our section pages (more on pages below). 
+* *template = "blog.html"* tells Zola to use `templates/blog.html` as the template for listing the Markdown files in this section. 
+* *page_template = "blog-page.html"* tells Zola to use `templates/blog-page.html` as the template for individual Markdown files. 
+
+For a full list of section variables, please see the [section](@/documentation/content/section.md) documentation.
+
+The value of our `title` variable here is available to templates such as `blog.html` as `{{ section.title }}`.
+
+If you now go to <http://127.0.0.1:1111/blog/>, you will see an empty list of posts.
+
+#### Markdown
+
+We'll now create some blog posts. Create `content/blog/first.md` with the following content.
+
+```md
++++
+title = "My first post"
+date = 2019-11-27
++++
+
+This is my first blog post.
+```
+
+The *title* and *date* will be available to us in the `blog-page.html` template as `{{ page.title }}` and `{{ page.date }}`, respectively. All text below the closing `+++` will be available to templates as `{{ page.content }}`.
+
+If you now go back to our blog list page at <http://127.0.0.1:1111/blog/>, you should see our lonely post. Let's add another. Create `content/blog/second.md` with the contents:
 
 ```md
 +++
@@ -218,9 +228,9 @@ date = 2019-11-28
 This is my second blog post.
 ```
 
-Back at <http://127.0.0.1:1111/blog/>, our second post shows up on top of the list because it's newer than the first post and we had set *sort_by = "date"* in our `_index.md` file. As a final step, let's modify our home page to link to our blog posts.
+Back at <http://127.0.0.1:1111/blog/>, our second post shows up on top of the list because it's newer than the first post and we had set *sort_by = "date"* in our `_index.md` file.
 
-The `index.html` file inside the `templates` directory should be:
+As a final step, let's modify `templates/index.html` (our home page) to link to our list of blog posts:
 
 ```html
 {% extends "base.html" %}
@@ -229,7 +239,7 @@ The `index.html` file inside the `templates` directory should be:
 <h1 class="title">
   This is my blog made with Zola.
 </h1>
-<p>Click <a href="{{/* get_url(path='@/blog/_index.md') */}}">here</a> to see my posts.</p>
+<p><a href="{{/* get_url(path='@/blog/_index.md') */}}">Posts</a>.</p>
 {% endblock content %}
 ```