English | 中文

A blog theme for zola, simple and clean.

Demo: https://serene-demo-site.vercel.app

• A spiffy design
• Projects page
• Dark mode
• Image zooming
• Out-of-date alert
• Sticky table-of-contents
• Callouts (note, warning, alert, etc.)
• Comments using Giscus
• Mathematical notations using KaTeX
• Diagrams and visualizations using Mermaid

If you haven't created a zola site yet, create a new zola site with the following command (assuming your site is called myblog):

zola init myblog

Enter the directory:

cd myblog

Add the serene theme:

git submodule add https://github.com/isunjn/serene.git themes/serene

The myblog directory now looks like this:

├── config.toml
├── content/
├── sass/
├── static/
├── templates/
└── themes/
    └── serene/

Create myblog/content/_index.md and myblog/content/blog/_index.md

If you want to display the projects page, also create myblog/content/projects/_index.md

├── config.toml
├── content/
│   ├── blog/
│   │   └── _index.md
│   ├── projects/
│   │   └── _index.md
│   └── _index.md
├── sass/
├── static/
├── templates/
└── themes/
    └── serene/

Modify the content of these files as follows:

myblog/content/_index.md:

+++
template = 'home.html'

[extra]
lang = 'en'
+++

Words about you

myblog/content/blog/_index.md:

+++
title = "My Blog"
description = "My blog site."
sort_by = "date"
template = "blog.html"
page_template = "post.html"
insert_anchor_links = "right"
generate_feed = true

[extra]
lang = 'en'
+++

myblog/content/projects/_index.md:

+++
title = "My Projects"
description = "My projects page."
template = "projects.html"

[extra]
lang = 'en'
+++

Create a new directory img under myblog/static, place favicon related files, you can use tools like favicon.io to generate

Also put your avatar picture file avatar.webp, webp format is recommended

...
├── static/
│   └── img/
│       ├── favicon-16x16.png
│       ├── favicon-32x32.png
│       ├── apple-touch-icon.png
│       └── avatar. webp
...

Copy the contents of myblog/themes/serene/config.example.toml to myblog/config.toml, refer to the comments in the file and Zola's documentation to modify accordingly

• Copy myblog/themes/serene/static/icon directory to myblog/static/icon, the icon value in links is the file name of the svg file in it, without the .svg suffix

• Find the svg file of the icon you want, modify its width and height to 24, and the color to currentColor:

  ... width="24" height="24" ... fill="currentColor" ...

• The default icons came from Remix Icon

• You can add rss to your site, Zola's default feed file is located in the root directory of the site, set generate_feed = true in config.toml, feed_filename can be set to atom.xml or rss.xml , corresponding to two different rss file standards, set generate_feed = false in myblog/content/blog/_index.md

• The serene theme looks more like a personal website, the posts are in the /blog directory, you may want the feed file to be in the /blog directory instead of the root directory, which requires you to set generate_feed = false feed_filename = "feed.xml" in config.toml, and set generate_feed = true in myblog/content/blog/_index.md

• feed.xml uses title and description from myblog/content/blog/_index.md, the other two use config.toml

• Serene has a projects page where you can showcase your projects, products, etc.

• Set projects_page = true in config.toml, create a new data.toml under myblog/content/projects, add projects information in it, the format is as follows:

  [[project]]
  name = ""
  desc = ""
  links = [
    { name = "", url = "" },
    { name = "", url = "" },
  ]
  
  [[project]]
  name = ""
  desc = ""
  links = [
    { name = "", url = "" },
    { name = "", url = "" },
  ]

• If one of your posts has strong timeliness, you can set an outdated alert to be displayed on the page after certain days

• outdate_alert and outdate_alert_days in config.toml set the default whether to be outdated and how many days to be outdated. These two can also be configured on a separate post, you can set outdate_alert in config.toml to false, and then enable it separately in the front matter of time-sensitive posts

• outdate_alert_text_before and outdate_alert_text_after are the specific content of the alert, before and after the number of days respectively

• Serene supports using giscus 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

• comment = true in config.toml sets all posts to enable comments, you can set comment = false under [extra] in the front matter of the post to control whether a specific post displays comments

• To place scripts for analytics tools (such as Google Anayltics, Umami, etc.), you can create a new myblog/templates/_head_extend.html and put the corresponding content in it. The content of this file will be added to the html head of each page

• Copy myblog/themes/serene/sass/main.scss to myblog/sass/main.scss, several variable values at the top of the file are used to control styles, such as the theme color --primary-color, modify it if you want

• Serene uses the Signika font of Google Fonts by default. If you want to customize the font, create a new myblog/templates/_custom_font.html and put the font link tag into it , and then modify --main-font or --code-font in myblog/sass/main.scss

• If you want to customize more, you only need to copy the files 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

• The content inside the two +++ at the top of the post markdown file is called front matter, and the supported configuration items are as follows:

  +++
  title = ""
  date = 2022-01-01
  draft = true
  
  [taxonomies]
  categories = ["one"]
  tags = ["one", "two", "three"]
  
  [extra]
  lang = "en"
  toc = true
  comment = true
  math = false
  mermaid = false
  outdate_alert = true
  outdate_alert_days = 120
  +++
  
  new post about somthing...
  
  <!-- more -->
  
  more post content...

• It is recommended to add a line <!-- more --> at the appropriate position in the post (such as after the first paragraph), and the content before it will be used as the description of the page, which is helpful for SEO

• Post files are created under myblog/content/blog, after done writing, change draft to true

• Zola supports Shortcodes, which can add some extra styles or templates for in addition to the standard markdown format

• In addition to ![img](/path/to/img) of standard markdown, Serene also supports a figure shortcode to add some explanatory text to the image, the format is as follows:

  {{ figure(src="/path/to/img", alt="alt text", caption="caption text") }}

  This will be displayed as <figure></figure> in HTML on the web page instead of <img>, and the content of the caption will be centered below the image. The alt attribute is optional but recommended to help enhance accessibility

  Adding attribution information to images is very common, you can directly use the via attribute, which will display a link named via below the image:

  {{ figure(src="/path/to/img", alt="some alt text", via="https://example.com") }}

• Serene also uses shortcodes to implement callouts, the effect is shown in this page of the demo site, there are currently 6 types: note important warning alert question tip, the format is as follows, the header attribute is optional:

  {% note(header="Note") %}
  note text
  {% end %}

• If people read your posts via rss reader, these callouts will appear as normal <blockquote>

• Set math = true in the front matter to enable KaTeX support

• Inline formula $...$, block-level formula $$...$$

• Set mermaid = true in the front matter to enable Mermaid support, and then insert a chart in the following format:

  {% mermaid() %}
  flowchart LR
  A[Hard] -->|Text| B(Round)
  B --> C{Decision}
  C -->|One| D[Result 1]
  C -->|Two| E[Result 2]
  {% end %}

Local preview:

zola serve

Build the site:

zola build

To deploy a static site, please refer to zola's documentation about deployment

Please check the CHANGELOG on github for breaking changes before updating the theme

git submodule update --remote themes/serene