From d96ddc7635dbe78f8a9ccdb53a4dca8b74ece9ba Mon Sep 17 00:00:00 2001
From: photong <57975239+photong@users.noreply.github.com>
Date: Mon, 20 Jan 2020 11:02:05 +0800
Subject: [PATCH] Docs next (#858)
* Update installation.md
* Update cli-usage.md
* Update installation.md
* Update directory-structure.md
* Update configuration.md
* Update overview.md
* Update section.md
* Update page.md
* Update section.md
* Update configuration.md
* Update page.md
* Update section.md
* Update page.md
* Update shortcodes.md
* Update linking.md
* Update table-of-contents.md
* Update syntax-highlighting.md
* Update taxonomies.md
* Update search.md
* Update sass.md
* Update index.md
* Update multilingual.md
* Update overview.md
* Update pages-sections.md
* Update pagination.md
* Update taxonomies.md
* Update rss.md
* Update sitemap.md
* Update robots.md
* Update 404.md
* Update archive.md
* Update overview.md
* Update installing-and-using-themes.md
* Update creating-a-theme.md
* Update netlify.md
* Update github-pages.md
* Update gitlab-pages.md
* Updates.
* Skip link checking for URL with prefix in config (#846)
* Fix some doc changes
* Section extra -> SitemapEntry (#850)
* Update deps
* Remove tutorial link.
* Update overview.md
* Update page.md
* Update section.md
* Update netlify.md
* Update overview.md
* Change some wording.
* Update overview.md
Co-authored-by: Tjeu Kayim <15987676+TjeuKayim@users.noreply.github.com>
Co-authored-by: Vincent Prouillet <balthek@gmail.com>
Co-authored-by: Stan Rozenraukh <stan@stanistan.com>
---
.../getting-started/configuration.md | 2 +-
.../getting-started/directory-structure.md | 2 +-
.../getting-started/installation.md | 2 +-
.../documentation/getting-started/overview.md | 206 ++++++++++++++++++
4 files changed, 209 insertions(+), 3 deletions(-)
create mode 100644 docs/content/documentation/getting-started/overview.md
diff --git a/docs/content/documentation/getting-started/configuration.md b/docs/content/documentation/getting-started/configuration.md
index 06b75063f4..ef031c0ee7 100644
--- a/docs/content/documentation/getting-started/configuration.md
+++ b/docs/content/documentation/getting-started/configuration.md
@@ -1,6 +1,6 @@
+++
title = "Configuration"
-weight = 4
+weight = 40
+++
The default configuration is sufficient to get Zola running locally but not more than that.
diff --git a/docs/content/documentation/getting-started/directory-structure.md b/docs/content/documentation/getting-started/directory-structure.md
index 7e003710d3..9feeab21c1 100644
--- a/docs/content/documentation/getting-started/directory-structure.md
+++ b/docs/content/documentation/getting-started/directory-structure.md
@@ -1,6 +1,6 @@
+++
title = "Directory structure"
-weight = 3
+weight = 30
+++
After running `zola init`, you should see the following structure in your directory:
diff --git a/docs/content/documentation/getting-started/installation.md b/docs/content/documentation/getting-started/installation.md
index d60539ae01..cac61233a5 100644
--- a/docs/content/documentation/getting-started/installation.md
+++ b/docs/content/documentation/getting-started/installation.md
@@ -1,6 +1,6 @@
+++
title = "Installation"
-weight = 1
+weight = 10
+++
Zola provides pre-built binaries for MacOS, Linux and Windows on the
diff --git a/docs/content/documentation/getting-started/overview.md b/docs/content/documentation/getting-started/overview.md
new file mode 100644
index 0000000000..b2a20d3725
--- /dev/null
+++ b/docs/content/documentation/getting-started/overview.md
@@ -0,0 +1,206 @@
++++
+title = "Overview"
+weight = 5
++++
+
+## Zola at a Glance
+
+Zola is a static site generator (SSG), similar to [Hugo](https://gohugo.io/), [Pelican](https://blog.getpelican.com/), and [Jekyll](https://jekyllrb.com/) (for a comprehensive list of SSGs, please see the [StaticGen](https://www.staticgen.com/) site). It is written in [Rust](https://www.rust-lang.org/) and uses the [Tera](https://tera.netlify.com/) template engine, which is similar to [Jinja2](https://jinja.palletsprojects.com/en/2.10.x/), [Django templates](https://docs.djangoproject.com/en/2.2/topics/templates/), [Liquid](https://shopify.github.io/liquid/), and [Twig](https://twig.symfony.com/). Content is written in [CommonMark](https://commonmark.org/), a strongly defined, highly compatible specification of [Markdown](https://www.markdownguide.org/).
+
+SSGs use dynamic templates to transform content into static HTML pages. Static sites are thus very fast and require no databases, making them easy to host. A comparison between static and dynamic sites, such as WordPress, Drupal, and Django, can be found [here](https://dev.to/ashenmaster/static-vs-dynamic-sites-61f).
+
+To get a taste of Zola, please see the quick overview below.
+
+## First Steps with Zola
+
+Unlike some SSGs, Zola makes no assumptions regarding the structure of your site. In this overview, we'll be making a simple blog site.
+
+### Initialize Site
+
+> This overview is based on Zola 0.9.
+
+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
+```
+
+You will be asked a few questions.
+
+```
+> What is the URL of your site? (https://example.com):
+> Do you want to enable Sass compilation? [Y/n]:
+> Do you want to enable syntax highlighting? [y/N]:
+> Do you want to build a search index of the content? [y/N]:
+```
+
+ 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
+├── static
+├── templates
+└── themes
+```
+
+Let's start the zola development server with:
+
+```bash
+$ zola serve
+Building site...
+-> Creating 0 pages (0 orphan), 0 sections, and processing 0 images
+```
+
+> This command must be run in the base Zola directory, which contains `config.toml`.
+
+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. We'll be using the CSS framework [Bulma](https://bulma.io/).
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+ <meta charset="utf-8">
+ <title>MyBlog</title>
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css">
+</head>
+
+<body>
+ <section class="section">
+ <div class="container">
+ {% block content %} {% endblock %}
+ </div>
+ </section>
+</body>
+
+</html>
+```
+
+Now, let's create an `index.html` file inside the `templates` directory.
+
+```html
+{% extends "base.html" %}
+
+{% block content %}
+<h1 class="title">
+ This is my blog made with Zola.
+</h1>
+{% endblock content %}
+```
+
+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
+```
+
+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:
+
+```html
+{% extends "base.html" %}
+
+{% block content %}
+<h1 class="title">
+ {{ section.title }}
+</h1>
+<ul>
+ {% for page in section.pages %}
+ <li><a href="{{ page.permalink }}">{{ 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 }}`, respectively. 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.
+
+### 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 avaiable 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:
+
+```html
+{% extends "base.html" %}
+
+{% block content %}
+<h1 class="title">
+ {{ page.title }}
+</h1>
+<p class="subtitle"><strong>{{ page.date }}</strong></p>
+<p>{{ page.content | safe }}</p>
+{% endblock content %}
+```
+
+> 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:
+
+```md
++++
+title = "My second post"
+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.
+
+The `index.html` file inside the `templates` directory should be:
+
+```html
+{% extends "base.html" %}
+
+{% block content %}
+<h1 class="title">
+ This is my blog made with Zola.
+</h1>
+<p>Click <a href="/blog/">here</a> to see my posts.</p>
+{% endblock content %}
+```
+
+This has been a quick overview of Zola. You can now dive into the rest of the documentation.