Merge branch 'dev' of https://github.com/nunocoracao/blowfish into dev

2026-01-30 16:31:52 +01:00 · 2025-06-17 22:30:23 +01:00
parent 771673c79a 4c92836470
commit c308942f0c
22 changed files with 187 additions and 40 deletions
--- a/.editorconfig
+++ b/.editorconfig
@@ -0,0 +1,10 @@
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
--- a/.prettierignore
+++ b/.prettierignore
@@ -0,0 +1,40 @@
+# https://github.com/gohugoio/hugo/blob/b39b24962350090122b5f3927456dde710cffb57/docs/.prettierignore
+# https://github.com/gohugoio/hugo/blob/b39b24962350090122b5f3927456dde710cffb57/docs/.prettierrc
+
+# develop
+.vscode
+node_modules
+package.json
+
+# Hugo
+assets/lib
+assets/css/compiled
+content
+themes
+public
+static
+*.md
+
+# Invalid nodes and unexpected tokens, mostly caused by unmatched tags in Hugo statements.
+# For example:
+# {{ with .Params.externalUrl }}
+# <a href="{{ . }}">
+#   {{ else }}
+#   <a href="{{ .RelPermalink }}" class="min-w-full">
+#     {{ end }}
+# 
+# This create an unclose node
+
+layouts/_default/_markup/render-heading.html
+layouts/_default/index.json
+layouts/_default/list.html
+layouts/partials/article-link/card-related.html
+layouts/partials/article-link/card.html
+layouts/partials/article-link/simple.html
+layouts/partials/header/basic.html
+layouts/partials/hero/background.html
+layouts/partials/head.html
+layouts/shortcodes/screenshot.html
+layouts/shortcodes/figure.html
+
+assets/js/appearance.js
--- a/.prettierrc
+++ b/.prettierrc
@@ -0,0 +1,45 @@
+{
+  "singleQuote": false,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "trailingComma": "all",
+  "proseWrap": "always",
+  "plugins": [
+    "prettier-plugin-go-template",
+    "@awmottaz/prettier-plugin-void-html"
+  ],
+  "overrides": [
+    {
+      "files": ["*.html"],
+      "options": {
+        "useTabs": false,
+        "parser": "go-template",
+        "goTemplateBracketSpacing": true,
+        "printWidth": 112,
+        "bracketSameLine": true
+      }
+    },
+    {
+      "files": ["*.js", "*.mjs", "*.mts", "*.ts"],
+      "options": {
+        "semi": true,
+        "useTabs": false,
+        "printWidth": 112,
+        "singleQuote": false
+      }
+    },
+    {
+      "files": ["*.yml", "*.yaml"],
+      "options": {
+        "singleQuote": false
+      }
+    },
+    {
+      "files": ["*.json*"],
+      "options": {
+        "trailingComma": "none"
+      }
+    }
+  ]
+}
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -45,7 +45,7 @@ The project includes a Prettier config that helps to format code in line with th

 #### Commit message guidelines

- Use [Gitmoji](https://gitmoji.dev) in commit messages to provide context.
+- Use [Gitmoji](https://gitmoji.dev) in PR messages to provide context.
 - Clearly describe the change with a short summary in the first 72 characters.
 - Place more detailed explanations in paragraphs below the summary, separated by a blank line.
 - Use imperative language (ie. "Fix bug", not "Fixed bug" or "Fixes bug").
--- a/config/_default/hugo.toml
+++ b/config/_default/hugo.toml
@@ -67,12 +67,3 @@ enableEmoji = true
      name = 'fragmentrefs'
      type = 'fragments'
      weight = 10
-
-[markup]
-  [markup.goldmark]
-    [markup.goldmark.extensions]
-      [markup.goldmark.extensions.passthrough]
-        enable = true
-        [markup.goldmark.extensions.passthrough.delimiters]
-          block = [['\[', '\]'], ['$$', '$$']]
-          inline = [['\(', '\)']]
--- a/config/_default/markup.toml
+++ b/config/_default/markup.toml
@@ -2,8 +2,15 @@
 # These settings are required for the theme to function.

 [goldmark]
-[goldmark.renderer]
-  unsafe = true
+  [goldmark.renderer]
+    unsafe = true
+
+  [goldmark.extensions]
+    [goldmark.extensions.passthrough]
+      enable = true
+      [goldmark.extensions.passthrough.delimiters]
+        block = [['\[', '\]'], ['$$', '$$']]
+        inline = [['\(', '\)']]

 [highlight]
  noClasses = false
--- a/exampleSite/config/_default/markup.toml
+++ b/exampleSite/config/_default/markup.toml
@@ -2,8 +2,15 @@
 # These settings are required for the theme to function.

 [goldmark]
-[goldmark.renderer]
-  unsafe = true
+  [goldmark.renderer]
+    unsafe = true
+
+  [goldmark.extensions]
+    [goldmark.extensions.passthrough]
+      enable = true
+      [goldmark.extensions.passthrough.delimiters]
+        block = [['\[', '\]'], ['$$', '$$']]
+        inline = [['\(', '\)']]

 [highlight]
  noClasses = false
--- a/exampleSite/content/docs/partials/index.it.md
+++ b/exampleSite/content/docs/partials/index.it.md
@@ -137,3 +137,11 @@ If you wish to insert additional code after article links, create a `layouts/par
 The theme allows for inserting additional code directly into the `<head>` and `<footer>` sections of the template. These can be useful for providing scripts or other logic that isn't part of the theme.

 Simply create either `layouts/partials/extend-head.html` or `layouts/partials/extend-footer.html` and these will automatically be included in your website build. Both partials are injected as the last items in `<head>` and `<footer>` so they can be used to override theme defaults.
+
+### Uncached Head Extension
+
+The `extend-head.html` is [cached](https://gohugo.io/functions/partials/includecached/), and Blowfish also supports an uncached head extension for **conditionally** including scripts or metadata based on page-level properties. To use this feature, create a `layouts/partials/extend-head-uncached.html` file in your project. This file will be included in `<head>` HTML tag.
+
+This is useful when you need to include dynamic elements—such as scripts or metadata—based on properties like shortcodes, front matter flags, or other page-specific data that should not be cached across builds.
+
+For example, to dynamically load a CDN JavaScript file base on the appearance of a shortcode, you can use the [HasShortcode](https://gohugo.io/methods/page/hasshortcode/#article) method within `extend-head-uncached.html`.
--- a/exampleSite/content/docs/partials/index.ja.md
+++ b/exampleSite/content/docs/partials/index.ja.md
@@ -137,3 +137,11 @@ Blowfish は、基本機能を拡張できる多数の拡張パーシャルも
 このテーマでは、テンプレートの `<head>` セクションと `<footer>` セクションに直接コードを追加できます。これらは、テーマの一部ではないスクリプトやその他のロジックを提供するのに役立ちます。

 `layouts/partials/extend-head.html` または `layouts/partials/extend-footer.html` を作成するだけで、これらは自動的にウェブサイトのビルドに含まれます。どちらのパーシャルも `<head>` と `<footer>` の最後の項目として挿入されるため、テーマのデフォルトを上書きするために使用できます。
+
+### 非キャッシュの head 拡張
+
+`extend-head.html` は[キャッシュされる](https://gohugo.io/functions/partials/includecached/)が、Blowfish ではページ単位の条件に応じてスクリプトやメタデータを動的に含めるための、非キャッシュの head 拡張にも対応している。この機能を使うには、プロジェクト内に `layouts/partials/extend-head-uncached.html` ファイルを作成する。このファイルは HTML の `<head>` タグ内に読み込まれる。
+
+これは、ショートコードや front matter のフラグなど、ビルド間でキャッシュされるべきでないページ固有の要素に基づいて、スクリプトやメタデータを動的に含めたい場合に有用。
+
+たとえば、ショートコードの有無に応じて CDN の JavaScript ファイルを読み込むには、`extend-head-uncached.html` 内で [HasShortcode](https://gohugo.io/methods/page/hasshortcode/#article) メソッドを使う。
--- a/exampleSite/content/docs/partials/index.md
+++ b/exampleSite/content/docs/partials/index.md
@@ -137,3 +137,11 @@ If you wish to insert additional code after article links, create a `layouts/par
 The theme allows for inserting additional code directly into the `<head>` and `<footer>` sections of the template. These can be useful for providing scripts or other logic that isn't part of the theme.

 Simply create either `layouts/partials/extend-head.html` or `layouts/partials/extend-footer.html` and these will automatically be included in your website build. Both partials are injected as the last items in `<head>` and `<footer>` so they can be used to override theme defaults.
+
+### Uncached Head Extension
+
+The `extend-head.html` is [cached](https://gohugo.io/functions/partials/includecached/), and Blowfish also supports an uncached head extension for **conditionally** including scripts or metadata based on page-level properties. To use this feature, create a `layouts/partials/extend-head-uncached.html` file in your project. This file will be included in `<head>` HTML tag.
+
+This is useful when you need to include dynamic elements—such as scripts or metadata—based on properties like shortcodes, front matter flags, or other page-specific data that should not be cached across builds.
+
+For example, to dynamically load a CDN JavaScript file base on the appearance of a shortcode, you can use the [HasShortcode](https://gohugo.io/methods/page/hasshortcode/#article) method within `extend-head-uncached.html`.
--- a/exampleSite/content/docs/partials/index.zh-cn.md
+++ b/exampleSite/content/docs/partials/index.zh-cn.md
@@ -140,3 +140,11 @@ Blowfish 还提供了许多扩展 partial，可以扩展基本功能。
 本主题允许在模板的`<head>`和`<footer>`部分直接插入附加代码。这些代码可用于提供不属于主题的脚本或其他逻辑。

 只需创建`layouts/partials/extend-head.html`或`layouts/partials/extend-footer.html`，这些部分就会自动包含在网站构建中。这两个 partial 将作为最后一项注入到 `<head>` 和 `<footer>` 中，因此它们可用于覆盖主题默认值。
+
+### 非缓存的 Head 扩展
+
+`extend-head.html` 是被[缓存](https://gohugo.io/functions/partials/includecached/)的，Blowfish 同时支持一种非缓存的 head 扩展方式，用于根据页面属性**条件性地**插入脚本或元数据。要使用此功能，请在项目中创建 `layouts/partials/extend-head-uncached.html` 文件，该文件会被插入到 `<head>` 标签中。
+
+此功能适用于根据 shortcode、front matter 标记或其他页面专属数据，动态添加脚本或元数据，避免内容在构建时被缓存。
+
+例如，可在 `extend-head-uncached.html` 中使用 [HasShortcode](https://gohugo.io/methods/page/hasshortcode/#article) 方法，根据 shortcode 是否存在动态加载 CDN JavaScript 文件。
--- a/exampleSite/content/docs/shortcodes/index.it.md
+++ b/exampleSite/content/docs/shortcodes/index.it.md
@@ -480,17 +480,17 @@ The `katex` shortcode can be used to add mathematical expressions to article con

 To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported.

-Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.
+Inline notation can be generated by wrapping the expression in `\(` and `\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.

 **Example:**

 ```md
 {{</* katex */>}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)
 ```

 {{< katex >}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)

 Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}}) page for more examples.

--- a/exampleSite/content/docs/shortcodes/index.ja.md
+++ b/exampleSite/content/docs/shortcodes/index.ja.md
@@ -480,17 +480,17 @@ Blowfish も、標準の Markdown 構文を使用して含まれる画像の自

 記事に数式を含めるには、コンテンツを含むショートコードを任意の場所に配置するだけです。記事ごとに1回だけ含める必要があり、KaTeX はそのページのマークアップを自動的にレンダリングします。インライン表記とブロック表記の両方がサポートされています。

-インライン表記は、式を `\\(` と `\\)` デリミタで囲むことで生成できます。また、ブロック表記は `$$` デリミタを使用して生成できます。
+インライン表記は、式を `\(` と `\)` デリミタで囲むことで生成できます。また、ブロック表記は `$$` デリミタを使用して生成できます。

 **例:**

 ```md
 {{</* katex */>}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)
 ```

 {{< katex >}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)

 [数式表記のサンプル]({{< ref "mathematical-notation" >}})ページで、その他の例を確認できます。

--- a/exampleSite/content/docs/shortcodes/index.md
+++ b/exampleSite/content/docs/shortcodes/index.md
@@ -484,17 +484,17 @@ The `katex` shortcode can be used to add mathematical expressions to article con

 To include mathematical expressions in an article, simply place the shortcode anywhere with the content. It only needs to be included once per article and KaTeX will automatically render any markup on that page. Both inline and block notation are supported.

-Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.
+Inline notation can be generated by wrapping the expression in `\(` and `\)` delimiters. Alternatively, block notation can be generated using `$$` delimiters.

 **Example:**

 ```md
 {{</* katex */>}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)
 ```

 {{< katex >}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)

 Check out the [mathematical notation samples]({{< ref "mathematical-notation" >}}) page for more examples.

--- a/exampleSite/content/docs/shortcodes/index.zh-cn.md
+++ b/exampleSite/content/docs/shortcodes/index.zh-cn.md
@@ -463,17 +463,17 @@ Blowfish 还支持使用标准 Markdown 语法自动转换图像。只需使用

 要在文章中加入数学表达式，只需将简码放在任意位置即可。每篇文章只需加入一次，KaTeX 将自动呈现该页面上的任何标记。支持内联和块表示法。

-可以通过将表达式包装在 `\\(` 和 `\\)` 分隔符中来生成内联表示法。或者，可以使用 `$$` 分隔符生成块符号。
+可以通过将表达式包装在 `\(` 和 `\)` 分隔符中来生成内联表示法。或者，可以使用 `$$` 分隔符生成块符号。

 **例如：**

 ```md
 {{</* katex */>}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)
 ```

 {{< katex >}}
-\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)
+\(f(a,b,c) = (a^2+b^2+c^2)^3\)

 查看 [数学符号示例]({{< ref "mathematical-notation" >}}) 页面以获取更多示例。

--- a/exampleSite/content/samples/mathematical-notation/index.it.md
+++ b/exampleSite/content/samples/mathematical-notation/index.it.md
@@ -21,16 +21,16 @@ Any KaTeX syntax on that page will then be automatically rendered. Use the onlin

 ## Inline notation

-Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters.
+Inline notation can be generated by wrapping the expression in `\(` and `\)` delimiters.

 **Example:**

 ```tex
 % KaTeX inline notation
-Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+Inline notation: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
 ```

-Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+Inline notation: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)

 ## Block notation

--- a/exampleSite/content/samples/mathematical-notation/index.ja.md
+++ b/exampleSite/content/samples/mathematical-notation/index.ja.md
@@ -22,16 +22,16 @@ Blowfish は数学的記法を利用する場合のみ、 KaTeX アセットを

 ## インライン表記

-インライン表記は `\\(` と `\\)` 記号で式を囲むことで生成できます。
+インライン表記は `\(` と `\)` 記号で式を囲むことで生成できます。

 **例:**

 ```tex
 % KaTeX インライン表記
-インライン表記: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+インライン表記: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
 ```

-インライン表記: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+インライン表記: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)

 ## ブロック表記

--- a/exampleSite/content/samples/mathematical-notation/index.md
+++ b/exampleSite/content/samples/mathematical-notation/index.md
@@ -21,16 +21,16 @@ Any KaTeX syntax on that page will then be automatically rendered. Use the onlin

 ## Inline notation

-Inline notation can be generated by wrapping the expression in `\\(` and `\\)` delimiters.
+Inline notation can be generated by wrapping the expression in `\(` and `\)` delimiters.

 **Example:**

 ```tex
 % KaTeX inline notation
-Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+Inline notation: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
 ```

-Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+Inline notation: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)

 ## Block notation

--- a/exampleSite/content/samples/mathematical-notation/index.zh-cn.md
+++ b/exampleSite/content/samples/mathematical-notation/index.zh-cn.md
@@ -21,16 +21,16 @@ KaTeX 可用于在文章中呈现数学表达式。

 ## 内联表示法

-可以通过将表达式包装在 `\\(` 和 `\\)` 分隔符中来生成内联表示法。
+可以通过将表达式包装在 `\(` 和 `\)` 分隔符中来生成内联表示法。

 **例如：**

 ```tex
 % KaTeX inline notation
-Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+Inline notation: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
 ```

-Inline notation: \\(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\\)
+Inline notation: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)

 ## 表达式块

--- a/layouts/shortcodes/gist.html
+++ b/layouts/shortcodes/gist.html
@@ -1 +1 @@
-<script src="https://gist.github.com/{{ index .Params 0 }}/{{ index .Params 1 }}.js{{if len .Params | eq 3 }}?file={{ index .Params 2 }}{{end}}"></script>
+<script src="https://gist.github.com/{{ index .Params 0 }}/{{ index .Params 1 }}.js{{if len .Params | eq 3 }} ?file={{ index .Params 2 }}{{end}}"></script>
--- a/package-lock.json
+++ b/package-lock.json
@@ -17,6 +17,7 @@
        "commander": "^14.0.0"
      },
      "devDependencies": {
+        "@awmottaz/prettier-plugin-void-html": "^1.8.0",
        "@tailwindcss/cli": "^4.1.8",
        "@tailwindcss/typography": "^0.5.16",
        "chart.js": "^4.4.9",
@@ -77,6 +78,19 @@
        "url": "https://github.com/sponsors/antfu"
      }
    },
+    "node_modules/@awmottaz/prettier-plugin-void-html": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@awmottaz/prettier-plugin-void-html/-/prettier-plugin-void-html-1.8.0.tgz",
+      "integrity": "sha512-gC1CO6TdjILFBc9UYJHY93RvM76jbNhb8IMiFzNbhyH1aCqvSVVjIhXCEQ9BkLyXGy8gmPfHX3m9BKHnl0edhQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=22.0.0"
+      },
+      "peerDependencies": {
+        "prettier": "3.0.0 - 3.5.x"
+      }
+    },
    "node_modules/@babel/code-frame": {
      "version": "7.23.5",
      "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.23.5.tgz",
--- a/package.json
+++ b/package.json
@@ -36,6 +36,7 @@
  },
  "homepage": "https://github.com/nunocoracao/blowfish#readme",
  "devDependencies": {
+    "@awmottaz/prettier-plugin-void-html": "^1.8.0",
    "@tailwindcss/cli": "^4.1.8",
    "@tailwindcss/typography": "^0.5.16",
    "chart.js": "^4.4.9",
@@ -123,4 +124,4 @@
    "@tailwindcss/forms": "^0.5.10",
    "commander": "^14.0.0"
  }
-}
+}