Mirrors/zola
2
0
Fork 0
mirror of https://github.com/getzola/zola synced 2024-11-10 06:14:19 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source
This commit is contained in:
orphen 2024-07-16 03:47:35 +09:00 committed by GitHub
parent c20b336cd9
commit 6390f65052
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 92 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
docs/content/documentation/getting-started/installation.md
View file

@ -175,7 +175,7 @@ jobs:
steps:
- uses: taiki-e/install-action@v2
with:
tool: zola@0.17.1
tool: zola@0.19.1
# ...
```
@ -187,26 +187,26 @@ 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
@ -214,7 +214,7 @@ Since there is no shell in the Zola docker image, if you want to use it from ins
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

162
docs/content/documentation/getting-started/overview.md
View file

@ -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.
### Templates
Listening for changes in .../myblog/{config.toml,content,sass,static,templates}
Press Ctrl+C to stop
We'll first create some templates to describe the structure of our site.
Web server is available at http://127.0.0.1:1111
```
#### Home Page Template
If you point your web browser to <http://127.0.0.1:1111>, you should see a "Welcome to Zola" message.
### Home Page
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
#### Blog Template
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
```
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,7 +122,8 @@ 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 %}
@ -172,26 +131,11 @@ Let's now create some more templates. In the `templates` directory, create a `bl
{% 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;`).
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;`).
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.
#### Blog Post Template
### Markdown Content
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 %}
```