diff options
Diffstat (limited to 'src/themes/serene/USAGE.md')
| -rw-r--r-- | src/themes/serene/USAGE.md | 323 |
1 files changed, 149 insertions, 174 deletions
diff --git a/src/themes/serene/USAGE.md b/src/themes/serene/USAGE.md index 1b91d88..88e73a1 100644 --- a/src/themes/serene/USAGE.md +++ b/src/themes/serene/USAGE.md @@ -1,5 +1,7 @@ This is the detailed guide on how to use zola-theme-serene. You should also check zola's [documentation](https://www.getzola.org/documentation/getting-started/overview/). +Serene requires zola `0.23.4` or later. + ## Installation Create a zola site and add serene theme (assuming your site is called `myblog`): @@ -11,13 +13,13 @@ git init git submodule add -b latest https://github.com/isunjn/serene.git themes/serene ``` -Copy the content of `myblog/themes/serene/config.example.toml` to `myblog/config.toml`. +Copy the content of `myblog/themes/serene/zola.toml.example` to `myblog/zola.toml`. ## Sections and Pages -There is a `sections` config option in your `config.toml`, which enumerates the sections your site has. You should have at least one `blog` section. +There is a `nav` config option in your `zola.toml`, which enumerates the navigation entries of the home page. An entry whose `path` starts with `/` links to a section of your site, any other path (e.g. an `https://` URL) is treated as an external link and opens in a new tab. You should have at least one `blog` section. -The name and path can be changed, be noticed that if you changed the blog section path (e.g. from `/posts` to `/blog`), then you should also change `blog_section_path` option. +The name and path can be changed, note that if you changed the blog section path (e.g. from `/posts` to `/blog`), then you should also change `blog_section_path` option. For home page, create `myblog/content/_index.md`: @@ -31,22 +33,10 @@ lang = 'en' # Show footer in home page footer = false -# If you don't want to display id/bio/avatar, simply comment out that line -name = "Serene Demo" -id = "serene" -bio = "programmer, he/him, we are young and life is fun" -avatar = "img/avatar.webp" -links = [ - { name = "GitHub", icon = "github", url = "https://github.com/<your-username>" }, - { name = "Twitter", icon = "twitter", url = "https://twitter.com/<your-username>" }, - { name = "Email", icon = "email", url = "mailto:<your-email-address>" }, -] - # Show a few recent posts in home page recent = false recent_max = 15 recent_more_text = "more »" -date_format = "%b %-d, %Y" +++ Hi, I'm ... @@ -59,7 +49,7 @@ For blog section, create `myblog/content/posts/_index.md`: title = "My Blog" description = "My blog site." sort_by = "date" -template = "blog.html" +template = "posts.html" page_template = "post.html" insert_anchor_links = "right" generate_feeds = true @@ -70,22 +60,14 @@ lang = "en" title = "Posts" subtitle = "I write about ...." -date_format = "%b %-d, %Y" - categorized = false # posts can be categorized back_to_top = true # show back-to-top button -toc = true # show table-of-contents -comment = false # enable comment -copy = true # show copy button in code block - -outdate_alert = false -outdate_alert_days = 12 -outdate_alert_text_before = "This article was last updated " -outdate_alert_text_after = " days ago and may be out of date." +++ ``` -Blog section is defined by `blog.html` and `post.html`. Serene also has a special template called `prose.html`, it applies the same styles of blog post page. You can use it as a section template for a custom section page, for example if you want a separate `about` page, you can add a `{ name = "about", path = "/about", is_external = false }` to the `sections` and create a `myblog/content/about/_index.md`: +Display options like `toc` / `code_copy` / `comment` / `date_format` have site-wide defaults in `zola.toml`, you can override them here for this section (e.g. `toc = false`), see [Front Matter](#front-matter) for details. + +Blog section is defined by `posts.html` and `post.html`. Serene also has a special template called `prose.html`, it applies the same styles of blog post page. You can use it as a section template for a custom section page, for example if you want a separate `about` page, you can add a `{ name = "about", path = "/about" }` to the `nav` and create a `myblog/content/about/_index.md`: ``` +++ @@ -97,25 +79,25 @@ insert_anchor_links = "none" [extra] lang = 'en' -title = "Posts" -subtitle = "I write about ...." - -math = false -mermaid = false -copy = false -comment = false -reaction = false +title = "About" +subtitle = "About this site" +++ Hi, My name is .... ``` -The default date format is "%b %-d, %Y", e.g. "Dec 13, 2025", check [this page](https://docs.rs/chrono/0.4.40/chrono/format/strftime/index.html) if you want to customize it, for example change to "%Y-%-m-%-d", e.g. "2025-2-13". +The default date format is "%b %-d, %Y", e.g. "Dec 13, 2025", check [this page](https://docs.rs/jiff/latest/jiff/fmt/strtime/index.html) if you want to customize it, for example change to "%Y-%-m-%-d", e.g. "2025-2-13". + +### Multiple list sections + +You can have more than one blog-like list section, e.g. a `series` section alongside `posts`. Just create `myblog/content/series/_index.md` the same way as the blog section (with `template = "posts.html"` and `page_template = "post.html"`), and add it to `nav` in `zola.toml`. Each list section has its own options in `[extra]` (`date_format`, `toc`, `categorized`, etc.), and can have its own feed by setting `generate_feeds = true` in its `_index.md` (available at e.g. `/series/feed.xml`). + +The `blog_section_path` option in `zola.toml` points to your *main* blog section, it is used by the recent posts list of the home page and by the tags pages (tags are site-wide: posts from all list sections that share a tag will be listed together). -Now the myblog directory may looks like this: +Now the myblog directory may look like this: ``` -├── config.toml +├── zola.toml ├── content/ │ ├── posts/ │ │ └── _index.md @@ -146,9 +128,9 @@ Create a new directory `img` under `myblog/static`, put favicon related files he ## Icon -The default icons are placed in `myblog/themes/serene/static/icon`, the `icon` value in `links` of home section is the file name of the svg file. +The default icons are placed in `myblog/themes/serene/static/icon`, the `icon` value in `links` of `zola.toml` is the file name of the svg file. -To customize, find the svg file you want, modify (in case you don't kown, a svg file is just a plian text file) its width and height to `18`, and the color to `currentColor`: +To customize, find the svg file you want, modify (in case you don't know, a svg file is just a plain text file) its width and height to `18`, and the color to `currentColor`: `... width="18" height="18" ... fill="currentColor" ...` @@ -158,25 +140,28 @@ The default icons mostly came from [Remix Icon](https://remixicon.com/). ## Theme -By default there is theme toggle button to switch between light and dark mode, you can set `force_theme` in `config.toml` to force a specific mode only. +The `color_scheme` option in `zola.toml` controls the light/dark mode behavior: `"auto"` (default) follows the visitor's system preference and shows a theme toggle button, while `"light"` / `"dark"` locks the site to a single mode and hides the button. -## Code Highlighting +## RSS -Copy `myblog/themes/serene/highlight_themes` directory to `myblog/highlight_themes`. +There are two ways to provide feeds: -By default serene use different highlight themes for light/dark mode, configured by `highlight_theme`, `extra_syntaxes_and_themes` and `highlight_themes_css`. The default highlight theme `serene-light` `serene-dark` is a modified version of [Tomorrow](https://github.com/ChrisKempson/Tomorrow-Theme) theme. +- **Per-section feeds** (recommended): set `generate_feeds = false` in `zola.toml`, and `generate_feeds = true` in the `_index.md` of your list sections. Each of these sections gets its own feed (e.g. `/posts/feed.xml`, `/series/feed.xml`), using the `title` and `description` of that section. The RSS button in the footer links to the feed of the section the current page belongs to. +- **A single site-wide feed**: set `generate_feeds = true` in `zola.toml`, and `generate_feeds = false` in section `_index.md` files. The feed is located in the root directory (e.g. `/feed.xml`), contains posts from all sections, and uses the `title` and `description` of `zola.toml`. The RSS button in the footer links to it on all pages. -If you set `highlight_theme` in `config.toml` to one of zola's [built-in highlight themes](https://www.getzola.org/documentation/getting-started/configuration/#syntax-highlighting), you will get that theme used in both light and dark mode. +`feed_filenames` can be set to `["feed.xml"]` (serene's own atom template), or `["atom.xml"]` / `["rss.xml"]` (zola's built-in templates), corresponding to different feed standards. -If you want a different theme, find the `.tmTheme` TextMate file of your theme, put it in `myblog/static/highlight_themes`, and then modify the `theme` value of `highlight_themes_css` to that file's name. This will generate a `hl-light.css` and a `hl-dark.css` file in `myblog/static/`, you may have to delete them first before you change the `theme` value, so zola can re-generate. You can find some TextMate themes on [this website](https://tmtheme-editor.glitch.me/). +## Open Graph -## RSS +Each page has [Open Graph](https://ogp.me/) and Twitter Card meta tags (plus a canonical link), so links shared to social media and chat apps can show a rich preview card with title, description and image. -Zola's default feed file is located in the root directory of the site, set `generate_feeds = true` in `config.toml`, `feed_filenames` can be set to `["atom.xml"]` or `["rss.xml"] ` , corresponding to two different rss file standards, you should also set `generate_feeds = false` in `myblog/content/posts/_index.md` +Title and description come from the same sources as the page's `<title>` and meta description. The preview image is resolved as follows: -The serene theme looks more like a personal website, the posts are in the `/posts` directory, you may want the feed file to be in the `/posts` directory instead of the root directory, this requires you to set `generate_feeds = false ` `feed_filenames = ["feed.xml"]` in `config.toml`, and set `generate_feeds = true` in `myblog/content/posts/_index.md`. +- Post pages use `og_image` in the `[extra]` section of front matter, if set. It can be a full URL, a path in the `static` folder (starting with `/`), or the filename of a [colocated asset](https://www.getzola.org/documentation/content/overview/#asset-colocation) of the post. +- Otherwise, the site-wide default `og_image` in the `[extra]` section of `zola.toml` is used, if set. It can be a full URL or a path in the `static` folder, e.g. `og_image = "img/og.png"`. +- If neither is set, image related tags are omitted. -`feed.xml` uses `title` and `description` from `myblog/content/posts/_index.md`, the other two use `config.toml`'s. +An image around 1200x630 is recommended for the best display on most platforms. ## Analytics @@ -186,9 +171,9 @@ To add scripts for analytics tools (such as Google Analytics, Umami, etc.), you Copy `myblog/themes/serene/templates/_custom_css.html` to `myblog/templates/_custom_css.html`, variables in this file are used to control styles, such as the theme color `--primary-color`, modify them as you want. -If you want to customize more, you need to copy that file under the `templates`, `static`, `sass` directory in the corresponding `themes/serene` to the same name directory of `myblog`, and modify it. Be careful not to directly modify the files under the serene directory, because these modifications may cause conflicts if the theme is updated. +If you want to customize more, copy the file you want to change from `themes/serene`'s `templates` / `static` / `sass` directory to the same-named directory of `myblog`, and modify it there. Be careful not to directly modify the files under the serene directory, because these modifications may cause conflicts if the theme is updated. -If you want to use a custom font, create a new `myblog/templates/_custom_font.html` and put the font link tags (for eample, from [google fonts](https://fonts.google.com/)) into it, and then modify `--main-font` or `--code-font` in `myblog/sass/templates/_custom_css.html`. For performance reason, you may want to self-host font files, but it's optional: +If you want to use a custom font, create a new `myblog/templates/_custom_font.html` and put the font link tags (for example, from [google fonts](https://fonts.google.com/)) into it, and then modify `--main-font` or `--code-font` in `myblog/templates/_custom_css.html`. For performance reasons, you may want to self-host font files, but it's optional: 1. Open [google-webfonts-helper](https://gwfh.mranftl.com) and choose your font. 2. Modify `Customize folder prefix` of step 3 to `/font/` and then copy the css. @@ -215,25 +200,26 @@ tags = ["one", "two", "three"] lang = "en" toc = true comment = false -copy = true -outdate_alert = true -outdate_alert_days = 120 +code_copy = true +outdated_alert = true +outdated_alert_days = 120 math = false mermaid = false featured = false reaction = false +og_image = "cover.png" +++ new post about something... ``` -Some of these options can also be configured in `myblog/content/posts/_index.md`, as the default value for all posts. +Display options follow a unified fallback chain: **post front-matter → the post's section `_index.md` → `[extra]` of `zola.toml`**, the closest one wins. This applies to `toc`, `code_copy`, `comment`, `math`, `mermaid`, `reaction`, `outdated_alert` and `outdated_alert_days` (`date_format` and `outdated_alert_text_before/after` follow a section → config chain). So you can set site-wide defaults in `zola.toml`, override them per section, and override again per post. -If you set `blog_categorized = true`, posts will be sorted alphabetically by default, you can manually set the order by adding a prefix `__[0-9]{2}__` in front of the category name, for example, `categories = ["__01__CatXXX"]` +If you set `categorized = true`, posts are grouped by category, and categories are sorted alphabetically by default, you can manually set the order by adding a prefix `__[0-9]{2}__` in front of the category name, for example, `categories = ["__01__CatXXX"]` ## Table of Contents -Set `toc = true` to display of table-of-contents. +Set `toc = true` to display the table-of-contents. ## Math & Chart @@ -245,19 +231,19 @@ Set `mermaid = true` to enable chart rendering with Mermaid. Set `featured = true` to display an asterisk(*) mark in front of the title. -## Outdate Alert +## Outdated Alert -If one of your posts has strong timeliness, you can display an outdate alert after certain days. +If one of your posts has strong timeliness, you can display an outdated alert after certain days. -Set `outdate_alert` and `outdate_alert_days` to enable the alert. +Set `outdated_alert` and `outdated_alert_days` to enable the alert. -In `myblog/content/posts/_index.md`, options `outdate_alert_text_before` and `outdate_alert_text_after` are the text content of the alert. +Options `outdated_alert_text_before` and `outdated_alert_text_after` are the text content of the alert, they can be set in `[extra]` of `zola.toml`, or per section in its `_index.md`. ## Comment You can use [giscus](https://giscus.app) as the comment system. -To enable it, you need to create `myblog/templates/_giscus_script.html` and put the script configured on the giscus website into it, then change the value of `data-theme` to `https://<your-domain-name>/giscus_light.css`, replace `<your-domain-name>` with you domain name, same as `base_url` in `config.toml`, if you set `force_theme` to `dark`, replace `giscus_light.css` with `giscus_dark.css`. +To enable it, you need to create `myblog/templates/_giscus_script.html` and put the script configured on the giscus website into it, then change the value of `data-theme` to `https://<your-domain-name>/giscus_light.css`, replace `<your-domain-name>` with you domain name, same as `base_url` in `zola.toml`, if you set `color_scheme` to `"dark"`, replace `giscus_light.css` with `giscus_dark.css`. Then set `comment = true` to enable comment. @@ -302,7 +288,7 @@ You need to setup a backend api endpoint to enable it. Your endpoint should hand } ``` -For conivence, you can use one template repo to to setup your own endpoint: +For convenience, you can use one template repo to setup your own endpoint: - [isunjn/reaction](https://github.com/isunjn/reaction): All you need is a [Cloudflare](https://cloudflare.com) account. The free tier is good enough for a low-traffic personal blog. @@ -317,169 +303,156 @@ Giscus also support a reaction feature, but it requires visitors to log in to Gi Zola supports some [annotations for code blocks](https://www.getzola.org/documentation/content/syntax-highlighting/#annotations). -## Shortcodes +## Callouts + +Callouts use the [GitHub alert syntax](https://github.com/orgs/community/discussions/16925), there are 5 types: `NOTE` `TIP` `IMPORTANT` `WARNING` `CAUTION`: + +```md +> [!NOTE] +> note text +``` + +Serene styles them with an icon and a title. The title texts default to "Note" / "Tip" / "Important" / "Warning" / "Caution", you can change them (e.g. for a non-English site) by setting css variables in your `_custom_css.html`: -[Shortcodes](https://www.getzola.org/documentation/content/shortcodes/) are some special templates. +```css +--callout-note-title: "注意"; +--callout-tip-title: "提示"; +--callout-important-title: "重要"; +--callout-warning-title: "警告"; +--callout-caution-title: "当心"; +``` + +## Components + +Since zola `0.23`, your markdown content is itself a [Tera](https://keats.github.io/tera/) template, and shortcodes were replaced by [Tera components](https://www.getzola.org/documentation/content/overview/#templating-your-content). Serene provides some built-in components. + +Note that component arguments other than strings are wrapped in `{...}`, e.g. `autoplay={true}`. -- Use `figure` to add caption to the image: +- Use `figure` to add caption or width/height to an image, `alt` `caption` `width` `height` are all optional (`width` and `height` take strings): ```md - {{ figure(src="/path/to/img", alt="alt text", caption="caption text") }} + {{ <figure src="/path/to/img" alt="alt text" caption="caption text" width="600" height="400" /> }} ``` - Adding attribution information to an image is very common, you can directly use the `via` attribute, which will display a link named 'via' below the image: + If `src` is the filename of a [colocated asset](https://www.getzola.org/documentation/content/overview/#asset-colocation), pass `page` (or `section` when used in a section's `_index.md`) so the image URL can be resolved: ```md - {{ figure(src="/path/to/img", alt="some alt text", via="https://example.com") }} + {{ <figure src="colocated-img.png" caption="caption text" page /> }} ``` + The caption is parsed as markdown so you can use bold / italic / link, for example `caption="[via](https://example.com)"` + + Adding height to an image is always recommended, as this can avoid page layout shift. When you use ``, browser cannot determine the image's dimensions before it loads. + - Use `quote` to display a special quote block, `cite` is optional: ```md - {% quote(cite="") %} + {% <quote cite=""> %} // content... - {% end %} + {% </quote> %} ``` - Use `detail` to add an expandable detail block, `default_open` is optional: ```md - {% detail(title="", default_open=false) %} + {% <detail title="" default_open={false}> %} // content... - {% end %} - ``` - -- As you can see in [this page](https://serene-demo.pages.dev/posts/callouts) of the demo site, callouts are special blockquote blocks, just like [github's](https://github.com/orgs/community/discussions/16925). There are currently 5 types: `note` `tip` `important` `warning` `caution`. - - `title` is optional: - - ```md - {% note(title="Note") %} - note text - {% end %} + {% </detail> %} ``` - Use `mermaid` to add a mermaid chart: ```md - {% mermaid() %} + {% <mermaid> %} flowchart LR A[Hard] -->|Text| B(Round) B --> C{Decision} C -->|One| D[Result 1] C -->|Two| E[Result 2] - {% end %} + {% </mermaid> %} ``` -## Collection +- Use `youtube` to embed a youtube video, `autoplay` is optional, default to `false`: -This theme has several special shortcodes for creating a collection of items. These collections can be used to showcase various types of your list, such as projects, publications, blogroll, bookmarks, etc. Check [this page](http://serene-demo.pages.dev/collections) on demo site to see some examples. + ```md + {{ <youtube id="<youtube-video-id>" autoplay={true} /> }} + ``` -Currently, there are 7 types of collection item: +Since your markdown content is now a Tera template, if you want to write literal `{{` or `{%` in your content (e.g. in a code block), wrap it with `{% raw %}` and `{% endraw %}`. -- `card` +Note that component calls must be at the top level of your content — don't nest them inside a list item, as the component's HTML output would break the list's indentation rules and produce broken HTML. - ```toml - [[collection]] - type = "card" - title = "Title" - subtitle = "Subtitle" # optional - date = "Date" # optional - link = "https://example.com" # optional - icon = "https://example.com/image.png" # optional - content = "Content" - tags = ["tag1", "tag2"] # optional - featured = false # optional - ``` +## Collection -- `card_simple` +This theme has a special component for creating a collection of items. Collections can be used to showcase various types of lists, such as projects, publications, blogroll, bookmarks, books, etc. Check [this page](https://serene-demo.pages.dev/collections) on demo site to see some examples. - ```toml - [[collection]] - type = "card_simple" - title = "Title" - date = "Date" # optional - link = "https://example.com" # optional - icon = "https://example.com/image.png" # optional - content = "Content" - featured = false # optional - ``` +A collection is described by a toml file. Two collection-level options decide how it looks: -- `entry` +- `layout`: the appearance of each item + - `card`: rich block item, with title / subtitle / content / tags etc. + - `row`: compact one-line item + - `tile`: small bordered block, text on the left and a 48x48 image on the right + - `gallery`: item with a poster image +- `flow`: how items are arranged in the container + - `stack`: vertically stacked, one item per line (default for `card` and `gallery`); a stacked `row` takes the full width with its `badge` aligned to the right + - `inline`: items take their content width and wrap horizontally (default for `row` and `tile`) + - `grid`: an even grid, the number of columns adapts to the available width automatically - ```toml - [[collection]] - type = "entry" - title = "Title" # optional - subtitle = "Subtitle" # optional - link = "https://example.com" # optional - icon = "https://example.com/image.png" # optional - ``` +Not every combination makes sense: `card` doesn't work with `flow = "inline"` (it is treated as `grid`), and an unknown `layout` / `flow` value falls back to the default. -- `box` +All layouts share the same set of item fields, every field except `title` is optional and simply omitted from rendering when absent. Each layout renders the fields that fit its density and ignores the rest: - ```toml - [[collection]] - type = "box" - title = "Title" - subtitle = "Subtitle" # optional - link = "https://example.com" # optional - img = "https://example.com/image.png" # optional - ``` - -- `art` +| field | card | row | tile | gallery | +| ---------- | ------------ | ---- | --------- | -------- | +| `title` | ✓ | ✓ | ✓ | ✓ | +| `subtitle` | ✓ | ✓ | ✓ | ✓ | +| `content` | ✓ | - | - | ✓ | +| `icon` | ✓ | ✓ | - | - | +| `image` | ✓ (left) | - | ✓ (48x48) | ✓ (poster) | +| `link` | title | title | whole item | title | +| `badge` | ✓ (right) | ✓ | - | ✓ (bottom) | +| `tags` | ✓ | - | - | - | +| `featured` | ✓ | ✓ | - | - | +| `rotate` | - | - | ✓ | - | - ```toml - [[collection]] - type = "art" - title = "Title" - subtitle = "Subtitle" # optional - link = "https://example.com" # optional - img = "https://example.com/image.png" - content = "Content" # optional - footer = "Footer" # optional - ``` - -- `art_simple` - - ```toml - [[collection]] - type = "art_simple" - title = "Title" - subtitle = "Subtitle" # optional - link = "https://example.com" # optional - img = "https://example.com/image.png" - ``` +```toml +layout = "card" # "card" | "row" | "tile" | "gallery" +# flow = "grid" # "stack" | "inline" | "grid" +[[item]] +title = "Title" +subtitle = "Subtitle" # supports inline markdown +content = "Content" # supports markdown +icon = "https://example.com/icon.png" # a small 16x16 icon shown before the title (card and row layouts) +image = "https://example.com/image.png" # a picture: shown on the left for card, as the 48x48 block for tile, as the poster for gallery +link = "https://example.com" # makes the title clickable (or the whole item for tile), external links open in a new tab automatically +# `icon` and `image` can be a full URL, a path in `static` (starting with `/`), or a file colocated with the section +badge = "2025" # a short mark rendered as-is: a year, a date range, a rating, a status... +tags = ["tag1", "tag2"] +featured = true # show an asterisk mark (card and row layouts) +rotate = true # playfully rotate the image (tile layout) +``` -List your items in a toml file and then use a `collection` shortcode to render them. +Note that `gallery` changes its look with the flow: `stack` puts the poster on the left with text on the right, while `grid` / `inline` puts the poster on top with text centered below. For example, to create a "projects" section page: 1. Create `myblog/content/projects/projects.toml`: ```toml - [[collection]] - type = "card" + layout = "card" + + [[item]] title = "Tokio" link = "https://example.com" - content = "Tokio is an asynchronous runtime for the Rust programming language. It provides the building blocks needed for writing network applications. It gives the flexibility to target a wide range of systems, from large servers with dozens of cores to small embedded devices." + content = "Tokio is an asynchronous runtime for the Rust programming language." tags = ["rust", "async", "runtime"] - [[collection]] - type = "card" + [[item]] title = "Kubernetes" link = "https://example.com" - content = "Kubernetes, also known as K8s, is an open source system for managing containerized applications across multiple hosts. It provides basic mechanisms for the deployment, maintenance, and scaling of applications." + content = "Kubernetes, also known as K8s, is an open source system for managing containerized applications." tags = ["k8s", "golang"] - - [[collection]] - type = "card" - title = "Next.js" - link = "https://example.com" - content = "Next.js is a React framework for building full-stack web applications. You use React Components to build user interfaces, and Next.js for additional features and optimizations." - tags = ["typescript", "react", "frontend"] - ``` 2. Create `myblog/content/projects/_index.md`: @@ -495,18 +468,20 @@ For example, to create a "projects" section page: subtitle = "Some cool projects I made" +++ - {{ collection(file="projects.toml") }} + {{ <collection file="projects.toml" section /> }} ``` -3. Add projects section in `sections` of `config.toml` +3. Add projects section in `nav` of `zola.toml` ```toml - sections = [ + nav = [ # ... - { name = "projects", path = "/projects", is_external = false }, + { name = "projects", path = "/projects" }, ] ``` +A page can have multiple collections: put several toml files in the section directory and call the component for each, with markdown headings in between to group them. + ## Build & Deploy Local preview: @@ -527,7 +502,7 @@ To deploy a static site, refer to zola's [documentation about deployment](https: Check the [CHANGELOG.md](https://github.com/isunjn/serene/blob/main/CHANGELOG.md) on github for breaking changes before you update. -If you copied some files from `myblog/themes/serene` to `myblog/` for customization, such as `_custom_css.html` or `main.scss`, then you should record what you have modified before you update, re-copy those files and re-apply your modification after updating. The `config.toml` should be re-copied too. +If you copied some files from `myblog/themes/serene` to `myblog/` for customization, such as `_custom_css.html` or `main.scss`, then you should record what you have modified before you update, re-copy those files and re-apply your modification after updating. The `zola.toml` should be re-copied too. You can watch (`watch > custom > releases > apply`) this project on github to be reminded of a new release. |