docs: add missing docs for the blake3 hash method

TISUnion · Dec 11, 2023 · c08b16d · c08b16d
1 parent b32d894
commit c08b16d
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 23 deletions.
diff --git a/docs/config.md b/docs/config.md
@@ -262,13 +262,13 @@ Prime Backup will save not only the `world` symbolic link, but also the `foo` sy
 
 #### hash_method
 
-The algorithm to hash the files. Available options: "xxh128", "sha256"
-
-- [`"xxh128"`](https://github.com/Cyan4973/xxHash): A extremely fast, high-quality 128bit non-cryptographic hash algorithm. 
-  Recommend to use, unless you want theoretic extreme safety on hackers
-- [`"sha256"`](https://en.wikipedia.org/wiki/SHA-2): A cryptographically secure and widely used 256bit hash algorithm.
-  It's slower than xxh128, but the speed could be acceptable with modern hardware
+The algorithm to hash the files. Available options: `"xxh128"`、`"sha256"`、`"blake3"`
 
+| Hash Method                                       | Description                                                                                                                                       | Speed | cryptographically secure |
+|---------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-------|--------------------------|
+| [`xxh128`](https://github.com/Cyan4973/xxHash)    | A extremely fast, high-quality 128bit non-cryptographic hash algorithm. Recommend to use, unless you want theoretic extreme safety on hackers     | ★★★★★ | :cross_mark:             |
+| [`sha256`](https://en.wikipedia.org/wiki/SHA-2)   | A cryptographically secure and widely used 256bit hash algorithm. It's slower than xxh128, but the speed could be acceptable with modern hardware | ★★    | :check_mark:             |
+| [`blake3`](https://github.com/BLAKE3-team/BLAKE3) | A cryptographically secure and speedy 256bit hash algorithm. It's still slower than xxh128, but is faster than sha256                             | ★★★   | :check_mark:             |
 
 !!! danger
 
@@ -277,6 +277,15 @@ The algorithm to hash the files. Available options: "xxh128", "sha256"
     If you do want to change the `hash_method`, you need to delete the `prime_backup.db` file and the `blobs` folder in the [storage root](#storage_root),
     which will delete all existing backups
 
+!!! note
+
+    If you want to use `blake3` as the hash method, you need to install the `blake3` python library manually.
+    It's not included in the default requirement list, because in some environments it might require rust runtime to build and install
+
+    ```bash
+    pip3 install blake3
+    ```
+
 - Type: `str`
 - Default: `"xxh128"`
 
@@ -298,7 +307,7 @@ The method to compress files stored in a backup
 
 !!! note
 
-    If you want to use `lz4` as the compress method, you need to install the lz4 python library manually
+    If you want to use `lz4` as the compress method, you need to install the `lz4` python library manually
 
     ```bash
     pip3 install lz4

diff --git a/docs/config.zh.md b/docs/config.zh.md
@@ -262,13 +262,13 @@ Prime Backup 除了会保存 `world` 这个符号链接外，还会保存 `foo`
 
 #### hash_method
 
-对文件进行哈希时所使用的算法。可用选项：`"xxh128"`、`"sha256"`
-
-- [`"xxh128"`](https://github.com/Cyan4973/xxHash):：一种极快的、高质量的 128 位哈希算法，不提供密码学安全性。
-  推荐使用，除非你想要理论上的极端安全
-- [`"sha256"`](https://en.wikipedia.org/wiki/SHA-2): 一种广泛使用的、密码学安全的 256 位哈希算法。
-  它比 xxh128 慢，但在现代的硬件上可能也不会太慢
+对文件进行哈希时所使用的算法。可用选项：`"xxh128"`、`"sha256"`、`"blake3"`
 
+| 哈希算法                                              | 描述                                                   | 速度    | 密码学安全性       |
+|---------------------------------------------------|------------------------------------------------------|-------|--------------|
+| [`xxh128`](https://github.com/Cyan4973/xxHash)    | 一种极快的、高质量的 128 位哈希算法，不提供密码学安全性。推荐使用，除非你想要理论上的极端安全    | ★★★★★ | :cross_mark: |
+| [`sha256`](https://en.wikipedia.org/wiki/SHA-2)   | 一种广泛使用的、密码学安全的 256 位哈希算法。它比 xxh128 慢，但在现代的硬件上可能也不会太慢 | ★★    | :check_mark: |
+| [`blake3`](https://github.com/BLAKE3-team/BLAKE3) | 一种高效的、密码学安全的哈希算法。比 sha256 更快，但是依然比 xxh128 慢          | ★★★   | :check_mark: |
 
 !!! danger
 
@@ -277,6 +277,15 @@ Prime Backup 除了会保存 `world` 这个符号链接外，还会保存 `foo`
     如果你确实需要修改 `hash_method`，你需要删除 [数据根目录](#storage_root) 路径下的 `prime_backup.db` 文件和 `blobs` 文件夹。
     这将删除所有的备份
 
+!!! note
+
+    如果你想使用 `blake3` 作为哈希算法，你需要手动安装 `blake3` Python 库。
+    它并不包含在默认的 Python 依赖列表中，因为它在某些情况下，可能需要 rust 环境来构建安装
+
+    ```bash
+    pip3 install blake3
+    ```
+
 - 类型：`str`
 - 默认值：`"xxh128"`
 
@@ -298,7 +307,7 @@ Prime Backup 除了会保存 `world` 这个符号链接外，还会保存 `foo`
 
 !!! note
 
-    如果你想使用 `lz4` 作为压缩方法，你需要手动安装 `lz4` python 库
+    如果你想使用 `lz4` 作为压缩方法，你需要手动安装 `lz4` Python 库
 
     ```bash
     pip3 install lz4

diff --git a/docs/quick_start.md b/docs/quick_start.md
@@ -72,12 +72,12 @@ Here are a few important things in the config file:
     }
     ```
 
-    - [`hash_method`](config.md#hash_method): The algorithm to hash the files. Available options: "xxh128", "sha256"
+    - [`hash_method`](config.md#hash_method): The algorithm to hash the files. Available options: "xxh128", "sha256", "blake3"
 
-        - [`"xxh128"`](https://github.com/Cyan4973/xxHash): A extremely fast, high-quality 128bit non-cryptographic hash algorithm. 
+        - [`"xxh128"`](https://github.com/Cyan4973/xxHash): A extremely fast, high-quality non-cryptographic hash algorithm. 
           Recommend to use, unless you want theoretic extreme safety on hackers
-        - [`"sha256"`](https://en.wikipedia.org/wiki/SHA-2): A cryptographically secure and widely used 256bit hash algorithm.
-          It's slower than xxh128, but the speed could be acceptable with modern hardware
+        - [`"sha256"`](https://en.wikipedia.org/wiki/SHA-2): A cryptographically secure and widely used hash algorithm
+        - [`"blake3"`](https://en.wikipedia.org/wiki/SHA-2): A cryptographically secure and speedy hash algorithm. Faster than sha256, but still slower than xxh128
 
     - [`compress_method`](config.md#compress_method): The way the backups get compressed. Common suggestions:
 
@@ -87,6 +87,15 @@ Here are a few important things in the config file:
     !!! danger
 
         You **CANNOT** change the `hash_method` after the plugin is enabled. Make your choice wisely
+
+    !!! note
+
+        If you want to use `blake3` as the hash method, you need to install the `blake3` python library manually.
+        It's not included in the default requirement list, because in some environments it might require rust runtime to build and install
+   
+        ```bash
+        pip3 install blake3
+        ```
     
     !!! warning
 

diff --git a/docs/quick_start.zh.md b/docs/quick_start.zh.md
@@ -72,12 +72,12 @@ mcdr_root/
     }
     ```
 
-    - [`hash_method`](config.zh.md#hash_method): 对文件进行哈希的算法。可用选项： "xxh128", "sha256"
+    - [`hash_method`](config.zh.md#hash_method): 对文件进行哈希的算法。可用选项： "xxh128", "sha256", "blake3"
 
-        - [`"xxh128"`](https://github.com/Cyan4973/xxHash):：一种极快的、高质量的 128 位哈希算法，不提供密码学安全性。
+        - [`"xxh128"`](https://github.com/Cyan4973/xxHash):：一种极快的、高质量的哈希算法，不提供密码学安全保证。
           推荐使用，除非你想要理论上的极端安全
-        - [`"sha256"`](https://en.wikipedia.org/wiki/SHA-2): 一种广泛使用的、密码学安全的 256 位哈希算法。
-          它比 xxh128 慢，但在现代的硬件上可能也不会太慢
+        - [`"sha256"`](https://en.wikipedia.org/wiki/SHA-2): 一种广泛使用的、密码学安全的哈希算法
+        - [`"blake3"`](https://en.wikipedia.org/wiki/SHA-2): 一种高效的、密码学安全的哈希算法。比 sha256 更快，但是依然比 xxh128 慢
 
     - [`compress_method`](config.zh.md#compress_method): 备份文件的压缩方式。常用建议：
 
@@ -87,6 +87,15 @@ mcdr_root/
     !!! danger
 
         你 **不能** 在启用插件后修改 `hash_method`。请明智地做出选择
+
+    !!! note
+
+        如果你想使用 `blake3` 作为哈希算法，你需要手动安装 `blake3` Python 库。
+        它并不包含在默认的 Python 依赖列表中，因为它在某些情况下，可能需要 rust 环境来构建安装
+
+        ```bash
+        pip3 install blake3
+        ```
 
     !!! warning
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -19,7 +19,11 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.superfences
   - pymdownx.snippets
-
+  # https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#configuration
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 theme:
   name: material
   features: