Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 1 commit into from
Jul 15, 2024
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions docs/content/documentation/getting-started/installation.md
View file
Open in desktop
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
Open in desktop
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