docs: v3.0.0 update

.gitignore

@@ -1,14 +1,8 @@
 public/
-
 content/
-
-!content/_index.md
-
 static/img/
-
+static/hl-light.css
+static/hl-dark.css
 config.toml
 
 .DS_Store
-
-static/hl-light.css
-static/hl-dark.css

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.0.0] - 2024-01-14
+
+> **Warning**
+> This version contains several breaking changes.
+> If you came from a previous version and want to upgrade, I suggest you start all over again.
+
+### Add:
+
+- `recent` homepage layout
+- `featured` mark
+- Add title to ToC when it's too long 
+- A way to sort categories
+- Project item image
+- prerender/prefetch when hover, using `speculationrules` or `prefetch` 
+- RSS mask
+- A few more css variables
+
+### Fix:
+
+- Theme init logic
+- Mobile sidebar ui
+
+### UI:
+
+- A few tweaks
+- Default icon size set to 20 (You should re-copy the `static/icon` folder)
+
+
 ## [2.3.0] - 2024-01-09
 
 ### Fix:
@@ -149,6 +177,7 @@ All notable changes to this project will be documented in this file.
 
 First release 🎉
 
+[3.0.0]: https://github.com/isunjn/serene/compare/v2.3.0...v3.0.0
 [2.3.0]: https://github.com/isunjn/serene/compare/v2.2.1...v2.3.0
 [2.2.1]: https://github.com/isunjn/serene/compare/v2.2.0...v2.2.1
 [2.2.0]: https://github.com/isunjn/serene/compare/v2.1.2...v2.2.0

README.md

@@ -1,6 +1,6 @@
-<img width="1501" alt="screenshot" src="https://github.com/isunjn/serene/assets/60461730/c3192aa5-945b-49f4-816d-861501d940ae">
+<img width="1501" alt="screenshot" src="https://github.com/isunjn/serene/assets/60461730/61b9ff3d-6ed3-4062-8872-1f3a3d9b60a7">
 
-<br /><br />
+<br />
 
 A blog theme for [zola](https://www.getzola.org), simple and clean
 
@@ -16,7 +16,7 @@ A blog theme for [zola](https://www.getzola.org), simple and clean
 - Image zooming
 - Out-of-date alert
 - Sticky table-of-contents
-- Callouts (note, warning, alert, etc.)
+- Callout (note, warning, alert, etc.)
 - Comments using [Giscus](https://giscus.app)
 - Mathematical notations using [KaTeX](https://katex.org)
 - Diagrams and visualizations using [Mermaid](https://github.com/mermaid-js/mermaid)
@@ -25,7 +25,3 @@ A blog theme for [zola](https://www.getzola.org), simple and clean
 
 - Check the [USAGE.md](https://github.com/isunjn/serene/blob/latest/USAGE.md) of `latest` branch
 - Also available in Simplified Chinese: [USAGE-zh_CN.md](https://github.com/isunjn/serene/blob/latest/USAGE-zh_CN.md) (简体中文)
-
-## Contributing
-
-- Before you make any non-trivial changes, you may want to open an issue so we can discuss

USAGE-zh_CN.md

@@ -131,7 +131,7 @@ Hi, My name is ....
 
 ## 配置
 
-### Favicons
+### Favicon
 
 在 `myblog/static` 下新建目录 `img` ，放置 favicon 相关图片，你可以使用类似 [favicon.io](https://favicon.io/favicon-converter/) 这样的工具在线生成
 
@@ -152,7 +152,7 @@ Hi, My name is ....
 
 - 将 `myblog/themes/serene/static/icon` 复制到 `myblog/static/icon`，links 中的 icon 值为其中的 svg 文件的文件名，不包含 `.svg` 后缀
 
-- 找到你想要的 icon 的 svg 文件，修改其宽高为 24，颜色为 currentColor: `... width="24" height="24" ... fill="currentColor" ...`
+- 找到你想要的 icon 的 svg 文件，修改其宽高为 20，颜色为 `currentColor`: `... width="20" height="20" ... fill="currentColor" ...`
 
 - 默认图标来自 [Remix Icon](https://remixicon.com/)
 
@@ -180,13 +180,14 @@ Hi, My name is ....
 
 - Serene 有一个 projects 页面，可以在其上展示你的项目、产品等信息
 
-- 在 `config.toml` 中设置 `projects_page = true` ，在 `myblog/content/projects/` 下新建一个 `data.toml` ，在其中添加项目信息，格式如下：
+- 在 `config.toml` 中设置 `projects_page = true` ，在 `myblog/content/projects/` 下新建一个 `data.toml` ，在其中添加项目信息，格式如下, 其中 `img` 是可选项：
 
   ```toml
   [[project]]
   name = ""
   desc = ""
   tags = ["", ""]
+  img = ""
   links = [
     { name = "", url = "" },
     { name = "", url = "" },
@@ -196,6 +197,7 @@ Hi, My name is ....
   name = ""
   desc = ""
   tags = ["", ""]
+  img = ""
   links = [
     { name = "", url = "" },
     { name = "", url = "" },
@@ -241,9 +243,12 @@ Hi, My name is ....
 
 ### 首页布局
 
-- 主页默认显示 `myblog/content/_index.md` 的 markdown 内容
+- 可通过 `config.toml` 中的 `homepage_layout` 改变首页布局
+
+  - `about`: 显示 `myblog/content/_index.md` 的 markdown 内容
+  - `list`: 显示和 `/blog` 相同的文章列表, 支持按 category 分类
+  - `recent`: 只显示最近的几篇文章
 
-- 可以将 `config.toml` 中的 `homepage_layout` 从 `about` 更改为 `list`，这样博客文章列表将直接显示在首页中
 
 ## 写作
 
@@ -272,6 +277,7 @@ Hi, My name is ....
   outdate_alert_days = 120
   display_tags = true
   truncate_summary = false
+  featured = false
   +++
 
   new post about something...
@@ -283,6 +289,10 @@ Hi, My name is ....
 
 - 你可以添加一行`<!-- more -->`, 在其前面的内容会成为文章的总结/描述, 可以设置 `truncate_summary = true` 来让其在最终的文章网页上不显示
 
+- 设置了 `featured = true` 的文章在列表中标题前方会显示一个 `*`, 可以用来标记你“最希望读者阅读”/“最有价值”的文章
+
+- 如果设置了文章列表按分类展示, 默认会按字母序排序, 可以在分类名前方加上 `__[0-9]{2}__` 这种形式的前缀来手动设置顺序, 例如 `categories = ["__01__Balabala"]`
+
 - 文章文件在 `myblog/content/blog` 下创建，写完后将 draft 改为 false 即可
 
 ### Shortcodes

USAGE.md

@@ -90,6 +90,7 @@ Serene also support a special template called `prose.html`, it applies the same
 title = "About me"
 description = "A about page of ..."
 template = "prose.html"
+insert_anchor_links = "none"
 
 [extra]
 lang = 'en'
@@ -129,7 +130,7 @@ Now the myblog directory may looks like this:
 
 ## Configuration
 
-### Favicons
+### Favicon
 
 - Create a new directory `img` under `myblog/static`, put favicon related files here, you can use tools like [favicon.io](https://favicon.io/favicon-converter/) to generate those files
 
@@ -150,9 +151,9 @@ Now the myblog directory may looks like this:
 
 - 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:
+- Find the svg file of the icon you want, modify its width and height to 20, and the color to `currentColor`:
 
-  `... width="24" height="24" ... fill="currentColor" ...`
+  `... width="20" height="20" ... fill="currentColor" ...`
 
 - The default icons came from [Remix Icon](https://remixicon.com/)
 
@@ -180,13 +181,14 @@ Now the myblog directory may looks like this:
 
 - Serene has a projects page where you can showcase your projects, products, etc.
 
-- Create a new `data.toml` under `myblog/content/projects/`, add projects information in it, the format is as follows:
+- Create a new `data.toml` under `myblog/content/projects/`, add projects information in it, the format is as follows, `img` is optional:
 
   ```toml
   [[project]]
   name = ""
   desc = ""
   tags = ["", ""]
+  img = ""
   links = [
     { name = "", url = "" },
     { name = "", url = "" },
@@ -196,6 +198,7 @@ Now the myblog directory may looks like this:
   name = ""
   desc = ""
   tags = ["", ""]
+  img = ""
   links = [
     { name = "", url = "" },
     { name = "", url = "" },
@@ -241,9 +244,11 @@ Now the myblog directory may looks like this:
 
 ### Homepage layout
 
-- By default, homepage displays markdown content of your `myblog/content/_index.md`
+- You can change the layout of the homepage by using the `homepage_layout` in `config.toml`
 
-- You can change `homepage_layout` in `config.toml` from `about` to `list`, then the blog post list will be displayed directly in the homepage
+  - `about`: displays markdown content of your `myblog/content/_index.md`
+  - `list`: the whole post list, can be categorized
+  - `recent`: only a few recent posts
 
 ## Writing
 
@@ -272,6 +277,7 @@ Now the myblog directory may looks like this:
   outdate_alert_days = 120
   display_tags = true
   truncate_summary = false
+  featured = false
   +++
 
   new post about something...
@@ -283,6 +289,10 @@ Now the myblog directory may looks like this:
 
 - You can add a `<!-- more -->` line, the content before it will become the summary/description of the post. You can set `truncate_summary = true` to remove the summary from the post webpage.
 
+- A post marked `featured = true` will display a `*` mark in front of it in list, you can use this to mark a post as "most worthy to read"  
+
+- If you set `blog_categorized = true`, posts will be sorted alphabetically by default, you can manually set the order by adding the prefix of `__[0-9]{2}__` in front of the category name, for example, `categories = ["__01__Balabala"]`
+
 - Post files are created under `myblog/content/blog`, after done writing, change `draft` to false
 
 ### Shortcodes

config.example.toml

@@ -1,4 +1,4 @@
-# serene v2.3.0
+# serene v3.0.0
 #
 # - docs: https://github.com/isunjn/serene/blob/latest/USAGE.md
 # - check for updates: https://github.com/isunjn/serene/releases
@@ -53,7 +53,7 @@ links = [                             # Your links
 
 homepage_layout = "about"             # "about" | "list" | "recent"
 
-recent_max = 5
+recent_max = 15
 recent_more = true
 recent_more_text = "more »"