diff --git a/docs/content/documentation/content/overview.md b/docs/content/documentation/content/overview.md index c81f7b28d1..c7792e112f 100644 --- a/docs/content/documentation/content/overview.md +++ b/docs/content/documentation/content/overview.md @@ -3,9 +3,7 @@ title = "Overview" weight = 10 +++ -Zola uses the directory structure to determine the site structure. -Each child directory in the `content` directory represents a [section](@/documentation/content/section.md) -that contains [pages](@/documentation/content/page.md) (your `.md` files). +Zola determines your site's structure from its directories. Each child folder in the `content` directory represents a separate [section](@/documentation/content/section.md)[^1]that contains [pages](@/documentation/content/page.md) (your `.md` files). ```bash . @@ -22,11 +20,11 @@ that contains [pages](@/documentation/content/page.md) (your `.md` files). └── _index.md // -> https://mywebsite.com/landing/ ``` -Each page path (the part after `base_url`, for example `blog/cli-usage/`) can be customised by changing the `path` or +Each page path (the part after `base_url`, for example `blog/cli-usage/`) can be customized by changing the `path` or `slug` attribute of the [page front-matter](@/documentation/content/page.md#front-matter). You might have noticed a file named `_index.md` in the example above. -This file is used to store both the metadata and content of the section itself and is not considered a page. +This file is used to store both the metadata and content of the section itself, and is not considered a page. To ensure that the terminology used in the rest of the documentation is understood, let's go over the example above. @@ -38,16 +36,15 @@ Sections can be nested indefinitely. ## Asset colocation -The `content` directory is not limited to markup files. It's natural to want to co-locate a page and some related +The `content` directory is not limited to markup files. It's natural to want to colocate a page and some related assets, such as images or spreadsheets. Zola supports this pattern out of the box for both sections and pages. All non-Markdown files you add in a page/section directory will be copied alongside the generated page when the site is built, which allows us to use a relative path to access them. -Pages with co-located assets should not be placed directly in their section directory (such as `latest-experiment.md`), but +Pages with colocated assets should not be placed directly in their section directory (such as `latest-experiment.md`), but as an `index.md` file in a dedicated directory (`latest-experiment/index.md`), like so: - ```bash └── research ├── latest-experiment @@ -72,10 +69,11 @@ It is possible to ignore selected asset files using the [ignored_content](@/documentation/getting-started/configuration.md) setting in the config file. For example, say that you have several code files which you are linking to on your website. For maintainability, you want to keep your code in the same directory as the Markdown file, -but you don't want to copy the build folders to the public web site. You can achieve this by setting `ignored_content` in the config file: +but you don't want to copy the build folders to the public website. You can achieve this by setting `ignored_content` in the config file: (Note of caution: `{Cargo.lock,target}` is _not_ the same as `{Cargo.lock, target}`) -``` + +```toml ignored_content = ["code_articles/**/{Cargo.lock,target}, *.rs"] ``` @@ -90,7 +88,7 @@ JavaScript) in the root of the static directory. You can also place any HTML or you wish to be included without modification (that is, without being parsed as Markdown files) into the static directory. -Note that the static directory provides an _alternative_ to co-location. For example, imagine that you +Note that the static directory provides an _alternative_ to colocation. For example, imagine that you had the following directory structure (a simplified version of the structure presented above): ```bash @@ -103,15 +101,18 @@ had the following directory structure (a simplified version of the structure pre ``` To add an image to the `https://mywebsite.com/blog/configuration` page, you have three options: - * You could save the image to the `content/blog/configuration` directory and then link to it with a - relative path from the `index.md` page. This is the approach described under **co-location** + +* You could save the image to the `content/blog/configuration` directory and then link to it with a + relative path from the `index.md` page. This is the approach described under **colocation** above. - * You could save the image to a `static/blog/configuration` directory and link to it in exactly the - same way as if you had co-located it. If you do this, the generated files will be identical to those - obtained if you had co-located the image; the only difference will be that all static files will be saved in the +* You could save the image to a `static/blog/configuration` directory and link to it in the same way as if you had colocated it. + If you do this, the generated files will be identical to those + obtained if you had colocated the image; the only difference will be that all static files will be saved in the static directory rather than in the content directory. The choice depends on your organizational needs. - * Or you could save the image to some arbitrary directory within the static directory. For example, - you could save all images to `static/images`. Using this approach, you can no longer use relative links. Instead, +* Or you could save the image to some arbitrary directory within the static directory. For example, + you could save all the images to `static/images`. Using this approach, you can no longer use relative links. Instead, you must use an absolute link to `images/[filename]` to access your image. This might be preferable for small sites or for sites that associate images with multiple pages (e.g., logo images that appear on every page). + +[^1]: Zola only considers content folders as sections if they contain an `_index.md` file. diff --git a/docs/content/documentation/content/section.md b/docs/content/documentation/content/section.md index 9a726e7bd9..9e3110f3e0 100644 --- a/docs/content/documentation/content/section.md +++ b/docs/content/documentation/content/section.md @@ -3,12 +3,16 @@ title = "Section" weight = 20 +++ -A section is created whenever a directory (or subdirectory) in the `content` section contains an -`_index.md` file. If a directory does not contain an `_index.md` file, no section will be -created, but Markdown files within that directory will still create pages (known as orphan pages). +A section is a collection of pages that's located within the `content/` folder. For example, on a blog, you may have a `content/posts/` folder. This `posts` folder would contain your blog posts. + +In addition to containing posts, every section has its own `_index.md` file that describes it and its posts. Like other parts of Zola, you can easily add different localizations by adding another file. For example, sites aiming to support French may give `_index.md` a matching `_index.fr.md`. + +If a folder is created in the `content/` directory, but it doesn't contain an `_index.md` file, Markdown files inside will still be rendered. However, no section will be created. The resulting pages are known as *orphan pages*. + +## Creation The homepage (i.e., the page displayed when a user browses to your `base_url`) is a section, -which is created whether or not you add an `_index.md` file at the root of your `content` directory. +which is created regardless of whether you add an `_index.md` file at the root of your `content` directory. If you do not create an `_index.md` file in your content directory, this main content section will not have any content or metadata. If you would like to add content or metadata, you can add an `_index.md` file at the root of the `content` directory and edit it just as you would edit any other @@ -19,14 +23,15 @@ Any non-Markdown file in a section directory is added to the `assets` collection Markdown file using relative links. ## Drafting -Just like pages sections can be drafted by setting the `draft` option in the front matter. By default this is not done. When a section is drafted it's descendants like pages, subsections and assets will not be processed unless the `--drafts` flag is passed. Note that even pages that don't have a `draft` status will not be processed if one of their parent sections is drafted. + +Just like pages, sections can be drafted by setting the `draft` option in the front matter. Sections are not drafted by default. When Zola encounters a drafted section, it will not process its descendants, including pages, subsections, and assets. Please note that even pages that don't have a `draft` status will not be processed if one of their parent sections is drafted. ## Front matter The `_index.md` file within a directory defines the content and metadata for that section. To set the metadata, add front matter to the file. -The TOML front matter is a set of metadata embedded in a file at the beginning of the file enclosed by triple pluses (`+++`). +The TOML front matter is a set of metadata embedded in a file at the beginning of the file, enclosed by triple pluses (`+++`). After the closing `+++`, you can add content, which will be parsed as Markdown and made available to your templates through the `section.content` variable. @@ -34,12 +39,11 @@ to your templates through the `section.content` variable. Although none of the front matter variables are mandatory, the opening and closing `+++` are required. Note that even though the use of TOML is encouraged, YAML front matter is also supported to ease porting -legacy content. In this case the embedded metadata must be enclosed by triple minuses (`---`). +legacy content. In this case, the embedded metadata must be enclosed by triple minuses (`---`). Here is an example `_index.md` with all the available variables. The values provided below are the default values. - ```toml title = "" @@ -130,7 +134,7 @@ by setting the `paginate_path` variable, which defaults to `page`. ## Sorting It is very common for Zola templates to iterate over pages or sections -to display all pages/sections in a given directory. Consider a very simple +to display all pages/sections in a given directory. Consider a basic example: a `blog` directory with three files: `blog/Post_1.md`, `blog/Post_2.md` and `blog/Post_3.md`. To iterate over these posts and create a list of links to the posts, a simple template might look like this: @@ -156,22 +160,26 @@ If several pages have the same date/weight/order, their permalink will be used to break the tie based on alphabetical order. ## Sorting pages + The `sort_by` front-matter variable can have the following values: ### `date` + This will sort all pages by their `date` field, from the most recent (at the top of the list) to the oldest (at the bottom of the list). Each page will get `page.lower` and `page.higher` variables that contain the pages with earlier and later dates, respectively. ### `update_date` -Same as `date` except it will take into account any `updated` date for the pages. + +Same as `date` except it will account for any `updated` date for the pages. ### `title` + This will sort all pages by their `title` field in natural lexical order, as -defined by `natural_lexical_cmp` in the [lexical-sort] crate. Each page will +defined by `natural_lexical_cmp` in the [lexical-sort] crate. Each page will get `page.lower` and `page.higher` variables that contain the pages -with previous and next titles, respectively. +with previous and next titles, respectively. For example, here is a natural lexical ordering: "bachata, BART, bolero, μ-kernel, meter, Métro, Track-2, Track-3, Track-13, underground". Notice how @@ -180,23 +188,27 @@ special characters and numbers are sorted reasonably. [lexical-sort]: https://docs.rs/lexical-sort ### `title_bytes` + Same as `title` except it uses the bytes directly to sort. -Natural sorting treats non-ascii -characters like their closest ascii character. This can lead to unexpected +Natural sorting treats non-ASCII +characters like their closest ASCII character. This can lead to unexpected results for languages with different character sets. The last three characters -of the Swedish alphabet, åäö, for example would be considered by the natural -sort as aao. In that case the standard byte-order sort may be more suitable. +of the Swedish alphabet, åäö, for example, would be considered by the natural +sort as aao. In that case, the standard byte-order sort may be more suitable. ### `weight` + This will sort all pages by their `weight` field, from the lightest weight (at the top of the list) to the heaviest (at the bottom of the list). Each page gets `page.lower` and `page.higher` variables that contain the pages with lighter and heavier weights, respectively. ### `slug` + This will sort pages or sections by their slug in natural lexical order. ### Reversed sorting + When iterating through pages, you may wish to use the Tera `reverse` filter, which reverses the order of the pages. For example, after using the `reverse` filter, pages sorted by weight will be sorted from lightest (at the top) to heaviest @@ -205,9 +217,10 @@ to newest (at the bottom). `reverse` has no effect on `page.lower` / `page.higher`. -If the section is paginated the `paginate_reversed=true` in the front matter of the relevant section should be set instead of using the filter. +If the section is paginated, the `paginate_reversed=true` in the front matter of the relevant section should be set instead of using the filter. ## Sorting subsections + Sorting sections is a bit less flexible: sections can only be sorted by `weight`, and do not have variables that point to the heavier/lighter sections. diff --git a/docs/content/documentation/content/shortcodes.md b/docs/content/documentation/content/shortcodes.md index fd652249a3..a1c01bc9be 100644 --- a/docs/content/documentation/content/shortcodes.md +++ b/docs/content/documentation/content/shortcodes.md @@ -9,16 +9,17 @@ In our case, a shortcode corresponds to a template defined in the `templates/sho Broadly speaking, Zola's shortcodes cover two distinct use cases: * Inject more complex HTML: Markdown is good for writing, but it isn't great when you need to add inline HTML or styling. -* Ease repetitive data based tasks: when you have [external data](@/documentation/templates/overview.md#load-data) that you +* Ease repetitive data-based tasks: when you have [external data](@/documentation/templates/overview.md#load-data) that you want to display in your page's body. -The latter may also be solved by writing HTML, however Zola allows the use of Markdown based shortcodes which end in `.md` -rather than `.html`. This may be particularly useful if you want to include headings generated by the shortcode in the +The latter may also be solved by writing HTML. However, Zola allows the use of Markdown based shortcodes which end in `.md` +rather than `.html`. This may be particularly useful if you'd like to include headings generated by the shortcode in the [table of contents](@/documentation/content/table-of-contents.md). -If you want to use something similar to shortcodes in your templates, you can use [Tera macros](https://keats.github.io/tera/docs#macros). They are functions or components that you can call to return some text. +If you wish to use something similar to shortcodes in your templates, you can use [Tera macros](https://keats.github.io/tera/docs#macros). They are functions or components that you can call to return some text. ## Writing a shortcode + Let's write a shortcode to embed YouTube videos as an example. In a file called `youtube.html` in the `templates/shortcodes` directory, paste the following: @@ -58,28 +59,27 @@ A Markdown based shortcode in turn will be treated as if what it returned was pa This will create a shortcode `books` with the argument `path` pointing to a `.toml` file where it loads lists of books with titles and descriptions. They will flow with the rest of the document in which `books` is called. -Shortcodes are rendered before the page's Markdown is parsed so they don't have access to the page's table of contents. +Shortcodes are rendered before the page's Markdown is parsed, so they don't have access to the page's table of contents. Because of that, you also cannot use the [`get_page`](@/documentation/templates/overview.md#get-page)/[`get_section`](@/documentation/templates/overview.md#get-section)/[`get_taxonomy`](@/documentation/templates/overview.md#get-taxonomy)/[`get_taxonomy_term`](@/documentation/templates/overview.md#get-taxonomy-term) global functions. It might work while -running `zola serve` because it has been loaded but it will fail during `zola build`. +running `zola serve` because it has been loaded, but it will fail during `zola build`. ## Using shortcodes There are two kinds of shortcodes: -- ones that do not take a body, such as the YouTube example above -- ones that do, such as one that styles a quote +* ones that do not take a body, such as the YouTube example above +* ones that do, such as one that styles a quote -In both cases, the arguments must be named and they will all be passed to the template. +In both cases, the arguments must be named and will be passed to the template. Parentheses are mandatory even if there are no arguments. -Note that while shortcodes look like normal Tera expressions, they are not Tera at all -- they can -pretty much just shuttle arguments to their template. Several limitions of note are: +Note that while shortcodes look like normal Tera expressions, they are not Tera at all -- they effectively shuttle arguments to their template. Several limitations of note are: -- All arguments are required -- The shortcode cannot reference Tera variables -- Concatenation and other operators are unavailable +* All arguments are required +* The shortcode cannot reference Tera variables +* Concatenation and other operators are unavailable -If the shortcode is invalid, it will not be interpreted by the markdown parser and will instead +If the shortcode is invalid, it will not be interpreted by the Markdown parser and will instead get rendered directly into the final HTML. Lastly, a shortcode name (and thus the corresponding `.html` file) as well as the argument names @@ -88,21 +88,21 @@ Although theoretically an argument name could be a number, it will not be possib Argument values can be of one of five types: -- string: surrounded by double quotes, single quotes or backticks -- bool: `true` or `false` -- float: a number with a decimal point (e.g., 1.2) -- integer: a whole number or its negative counterpart (e.g., 3) -- array: an array of any kind of value, except arrays +* string: surrounded by double quotes, single quotes or backticks +* bool: `true` or `false` +* float: a number with a decimal point (e.g., 1.2) +* integer: a whole number or its negative counterpart (e.g., 3) +* array: an array of any kind of value, except arrays Malformed values will be silently ignored. Both types of shortcode will also get either a `page` or `section` variable depending on where they were used -and a `config` variable. These values will overwrite any arguments passed to a shortcode so these variable names +and a `config` variable. These values will overwrite any arguments passed to a shortcode, so these variable names should not be used as argument names in shortcodes. ### Shortcodes without body -Simply call the shortcode as if it was a Tera function in a variable block. +Simply call the shortcode as if it were a Tera function in a variable block. ```md Here is a YouTube video: @@ -118,6 +118,7 @@ Note that if you want to have some content that looks like a shortcode but not h you will need to escape it by using `{{/*` and `*/}}` instead of `{{` and `}}`. ### Shortcodes with body + Let's imagine that we have the following shortcode `quote.html` template: ```jinja2 @@ -141,10 +142,12 @@ The body of the shortcode will be automatically passed down to the rendering con to be on a new line. ### Shortcodes with no arguments -Note that for both cases that the parentheses for shortcodes are necessary. + +Note that for both cases that the parentheses for shortcodes are necessary. A shortcode without the parentheses will render as plaintext and no warning will be emitted. As an example, this is how an `aside` shortcode-with-body with no arguments would be defined in `aside.html`: + ```jinja2