Docs next #858

photong · 2019-11-27T11:30:24Z

This is a new overview section for "Getting Started". It gives an overview of what Zola is and provides a very quick tutorial on how to achieve a basic blog. This will be very helpful for new users.

Keats

A few tweaks imo but looks good.
I'm wondering how this quickstart would look if Zola had a default theme like asked in #672

What do you think?

Keats · 2019-11-27T18:56:06Z

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

@@ -0,0 +1,202 @@
+++
+title = "Overview"


can we call that Quickstart?

Regarding default theme, yes, that would be great. Bulma (bulma.io) and Spectre (https://picturepan2.github.io/spectre/) are two ligthweight CSS frameworks. Maybe something based on them?

I called this section "Overview" to be consistent with other sections (they all have an "Overview" page) and this page gives an overview of Zola and how it works. Quickstart is also good.

I do not think we should use any CSS framework for a default theme. It is easy to write a theme without framework (I did one https://git.42l.fr/HugoTrentesaux/toucan) and it makes the template easier to read and modify and shows better the interest of native SASS compilation. I made a theme with Bulma (https://git.42l.fr/HugoTrentesaux/dunitrust_website) and I am currently thinking about a rewrite without it. If I had to choose a framework, I would rather go to https://www.knacss.com/ or https://purecss.io/. But this is really a question of taste. We can later develop themes for each of this frameworks, but for now, I prefer to stick to CSS.

The toucan theme is great for showing SASS integration. I'll use it for the full tutorial. For the Quickstart, I'll remove Bulma and use toucan if it's the default. If not, it's probably ok to just use pure HTML because it's meant to just give a quick taste of Zola, not produce an actual site.

I agree with removing Bulma/any css for the quickstart. It is not that important for a Zola quickstart.

Keats · 2019-11-27T18:59:09Z

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

+
+## 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 [Markdown](https://www.markdownguide.org/).


Content is written in CommonMark https://commonmark.org/
I think it's important to mention that since there are many flavours of Markdown.

Yes, that's very important. I'll update it to CommonMark.

Content is written in CommonMark, a strongly defined, highly compatible specification of Markdown.

Keats · 2019-11-27T19:04:03Z

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

+
+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).
+
+If you are new to SSGs, please see the quick overview below.


Everything below seem specific to Zola though?

I was thinking that people familiar with Hugo, Pelican, Jekyll, etc. would know about the basics (templates, Markdown, etc.), but I see your point. I'll change it to "To get a taste of Zola, please see the quick overview below.".

Keats · 2019-11-27T19:11:37Z

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

+
+> This command must be run in the base Zola directory, which contains `config.toml`.
+
+If you point your web browser to [127.0.0.1:1111](http://127.0.0.1:1111), you should see a "Welcome to Zola" message.


In Markdown you can automatically have links like that by doing <http://127.0.0.1:1111> instead of [127.0.0.1:1111](http://127.0.0.1:1111).

Keats · 2019-11-27T19:17:34Z

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

+
+> 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).


This might be more readable as a bullet list?

I'll make this a bullet list. Is italics ok for variable names and values?

Keats · 2019-11-27T20:02:08Z

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

+
+### Templates
+
+Let's now create some templates. In the `templates` directory, create a `blog.html` file with the following contents:


We've already created the homepage! Maybe "some more templates"?

Oops. Yes, "some more".

Keats · 2019-11-27T20:02:48Z

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

+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 }}`.


The text below will be available as HTML

"All text below the closing +++ will be available as HTML in the {{ page.content }} variable."? I'm currently using for directories and template variables names (TOML variables are in italics). Should I change to bold for template variables?

Keats · 2019-11-27T20:06:13Z

cc @Hugo-Trentesaux

…-next

Keats · 2019-12-10T09:52:59Z

@photong Do you have more changes coming?

photong · 2019-12-10T23:56:12Z

I'll make a few more changes this weekend.

photong · 2019-12-15T14:01:22Z

I'll need a few more days.

Keats · 2019-12-15T19:42:14Z

No worries, take your time

Keats · 2020-01-02T10:18:55Z

@photong let me know if I can help!

photong · 2020-01-04T02:49:44Z

Yes, please. Sorry for the radio silence. I've had some work/family things going on and don't have much free time.

Keats · 2020-01-11T09:42:38Z

What can I do to help?

Keats · 2020-01-20T03:02:11Z

I'll merge that for now to avoid potential conflicts. Thanks a lot

* 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 <[email protected]> Co-authored-by: Vincent Prouillet <[email protected]> Co-authored-by: Stan Rozenraukh <[email protected]>

photong added 30 commits November 21, 2019 08:33

Update installation.md

b678c82

Update cli-usage.md

9603032

Update installation.md

86200f2

Update directory-structure.md

9750098

Update configuration.md

44ce379

Update overview.md

1251dee

Update section.md

751bea3

Update page.md

6327c75

Update section.md

3c379d3

Update configuration.md

d20eb8c

Update page.md

19c511c

Update section.md

9cef2ca

Update page.md

80fa637

Update shortcodes.md

b9ba051

Update linking.md

91a1f31

Update table-of-contents.md

e5087bd

Update syntax-highlighting.md

8af696d

Update taxonomies.md

e4bb3a8

Update search.md

785deb7

Update sass.md

d63008d

Update index.md

614099d

Update multilingual.md

f568f92

Update overview.md

02f6633

Update pages-sections.md

eaf7771

Update pagination.md

4a0e67a

Update taxonomies.md

b1739fb

Update rss.md

70a48e7

Update sitemap.md

30ea9e8

Update robots.md

d3ac9a2

Update 404.md

a1ec03d

photong and others added 15 commits November 22, 2019 16:16

Update netlify.md

60ab8f7

Update github-pages.md

dcd16e6

Update gitlab-pages.md

eca7a04

Updates.

e0dd168

Merge branch 'next' into docs-next

7dfab02

Skip link checking for URL with prefix in config (#846)

7bb482b

Fix some doc changes

7850603

Section extra -> SitemapEntry (#850)

0c2147f

Update deps

358c1c8

Remove tutorial link.

a7b2591

Update overview.md

9f27c60

Update page.md

7aebe9a

Update section.md

264cd71

Update netlify.md

070c206

Update overview.md

c59312d

Keats requested changes Nov 27, 2019

View reviewed changes

photong and others added 3 commits November 28, 2019 16:03

Change some wording.

417ed4a

Merge branch 'docs-next' of https://github.com/photong/zola into docs…

34e24fd

…-next

Update overview.md

35bdcfb

Keats merged commit d96ddc7 into getzola:next Jan 20, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs next #858

Docs next #858

photong commented Nov 27, 2019

Keats left a comment

Keats Nov 27, 2019

photong Nov 28, 2019

Hugo-Trentesaux Nov 28, 2019

photong Nov 28, 2019 •

edited

Loading

Keats Dec 1, 2019

Keats Nov 27, 2019

photong Nov 28, 2019

photong Nov 28, 2019

Keats Nov 27, 2019

photong Nov 28, 2019

Keats Nov 27, 2019

photong Nov 28, 2019

Keats Nov 27, 2019

photong Nov 28, 2019

Keats Nov 28, 2019

Keats Nov 27, 2019

photong Nov 28, 2019

Keats Nov 27, 2019

photong Nov 28, 2019

Keats commented Nov 27, 2019

Keats commented Dec 10, 2019

photong commented Dec 10, 2019

photong commented Dec 15, 2019

Keats commented Dec 15, 2019

Keats commented Jan 2, 2020

photong commented Jan 4, 2020

Keats commented Jan 11, 2020

Keats commented Jan 20, 2020


		## 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 [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).

		If you are new to SSGs, please see the quick overview below.


		> This command must be run in the base Zola directory, which contains `config.toml`.

		If you point your web browser to [127.0.0.1:1111](http://127.0.0.1:1111), you should see a "Welcome to Zola" message.


		> 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 templates. In the `templates` directory, create a `blog.html` file with the following contents:

Docs next #858

Docs next #858

Conversation

photong commented Nov 27, 2019

Keats left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

photong Nov 28, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Keats commented Nov 27, 2019

Keats commented Dec 10, 2019

photong commented Dec 10, 2019

photong commented Dec 15, 2019

Keats commented Dec 15, 2019

Keats commented Jan 2, 2020

photong commented Jan 4, 2020

Keats commented Jan 11, 2020

Keats commented Jan 20, 2020

photong Nov 28, 2019 •

edited

Loading