Skip to content

Commit

Permalink
docs: fix order of events in zola overview (templates, server, conten…
Browse files Browse the repository at this point in the history 
…t) (getzola#2574)
  • Loading branch information
@iamorphen @berdandy
iamorphen authored and berdandy committed Sep 17, 2024
1 parent 0115617 commit c77cdd4
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 82 deletions.
12 changes: 6 additions & 6 deletions docs/content/documentation/getting-started/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ jobs:
steps:
- uses: taiki-e/install-action@v2
with:
tool: zola@0.17.1
tool: zola@0.19.1
# ...
```

Expand All @@ -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
Expand Down
162 changes: 86 additions & 76 deletions docs/content/documentation/getting-started/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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
Expand Down Expand Up @@ -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>
Expand All @@ -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" %}
Expand All @@ -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" %}
Expand All @@ -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" %}
Expand All @@ -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
+++
Expand All @@ -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" %}
Expand All @@ -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 %}
```

Expand Down

0 comments on commit c77cdd4

Please sign in to comment.