diff --git a/exampleSite/content/docs/advanced/purgecss/index.md b/exampleSite/content/docs/advanced/purgecss/index.md new file mode 100644 index 000000000..4f3de89bb --- /dev/null +++ b/exampleSite/content/docs/advanced/purgecss/index.md @@ -0,0 +1,72 @@ ++++ +# type = "docs" +title = "PurgeCSS" +date = 2022-07-25T12:06:00+08:00 +# description = "" # Used by description meta tag, summary will be used instead if not set or empty. +featured = false +draft = false +comment = true +toc = true +reward = true +pinned = false +carousel = false +categories = ["PurgeCSS"] +tags = [] +series = ["Docs"] +images = [] ++++ + +The PurgeCSS is an awesome tool that remove unused CSS from your site. +In this section, we will dive into how the PurgeCSS work, and what should we pay attention to. + + + +## How it Works? + +The PurgeCSS requires the following configuration to be set. + +{{< code-toggle filename="config" >}} +{{% config/build-write-stat %}} +{{}} + +It tells Hugo to calculate used tags, classes and ids, and then generates the `hugo_stats.json`. + +{{% code/purgecss-hugo-stats %}} + +Finally PurgeCSS relies on this file to purge unused CSS. + +> The PurgeCSS works only under `production` environment. + +> We **DON NOT** recommend overriding the those files.`postcss.config.js` and `assets/main/config/rtl/postcss.config.js`, otherwise, unexpected problems will occur during version updates. + +## Limitations + +**The `hugo_stats.json` only works in `*.html` templates**, that is, any CSS classes, tags and ids used on JavaScript files will still be purged. + +But don worry, there are two ways to solve this problem. + +### Extra Stats + +Just create a file called `extra_stats.json` with the same form of `hugo_stats.json` on your site root, and put the extra CSS into it manually. + +> `extra_stats.json` MUST be commited to your repo. + +### Put HTML Block into `*.html` Files + +A common scenario is rendering HTML blocks using JavaScript, if you're using JavaScript to generate DOM element, any used CSS will be ignored by `hugo_stats.json`. Of course you can add it to `extra_stats.json` manually, but there is a better way to do that via template engine. + +1. Firstly, we'll need to define a template block in `*.html` partials. + +{{% code/purgecss-template-partial %}} + +Hugo will calculate used CSS into `hugo_stats.json`, such as the `search-results` class. + +1. And then render the template via any template engines. + +{{% code/purgecss-template-js %}} + +## Testing + +You'll need to specify the `production` environment for local testing via `hugo server -e production -b http://localhost:1313`, since the PurgeCSS only works on `production` environment. + +Sometimes PurgeCSS and PostProcess don't work very well, so you may need to restart Hugo Server occasionally. diff --git a/exampleSite/content/docs/advanced/purgecss/index.zh-hans.md b/exampleSite/content/docs/advanced/purgecss/index.zh-hans.md new file mode 100644 index 000000000..ef5e9aeb9 --- /dev/null +++ b/exampleSite/content/docs/advanced/purgecss/index.zh-hans.md @@ -0,0 +1,71 @@ ++++ +# type = "docs" +title = "PurgeCSS" +date = 2022-07-25T12:06:00+08:00 +# description = "" # Used by description meta tag, summary will be used instead if not set or empty. +featured = false +draft = false +comment = true +toc = true +reward = true +pinned = false +carousel = false +categories = ["PurgeCSS"] +tags = [] +series = ["文档"] +images = [] ++++ + +PurgeCSS 是一个很棒的工具,可以从你的网站上删除未使用的 CSS。 +在本节中,我们将深入探讨 PurgeCSS 是如何工作的,以及我们应该注意什么。 + + + +## 它是如何工作的? + +PurgeCSS 需要设置以下配置。 + +{{< code-toggle filename="config" >}} +{{% config/build-write-stat %}} +{{}} + +其告诉 Hugo 计算已使用的标签、类和 ID,然后生成`hugo_stats.json`。 + +{{% code/purgecss-hugo-stats %}} + +最后 PurgeCSS 依靠这个文件来清除未使用的 CSS。 + +> PurgeCSS 只在 `production` 环境下工作。 + +> 我们**不建议**覆盖这些文件 `postcss.config.js` 和 `assets/main/config/rtl/postcss.config.js`,否则在版本更新中会出现意想不到的问题。 + +## 局限性 + +**`hugo_stats.json` 只适用于 `*.html` 模板**,也就是说,任何用于 JavaScript 文件的 CSS 类、标签和 ID 仍然会被清除。 +但是不要担心,有两种方法可以解决这个问题。 + +### 额外的统计 + +只要在你的网站根目录下创建一个名为 `extra_stats.json` 的文件,其形式与 `hugo_stats.json` 相同,并手动将额外的 CSS 放入其中。 + +> `extra_stats.json` 必须被提交到你的仓库中。 + +### 将HTML块放入 `*.html` 文件中 + +一个常见的情况是使用 JavaScript 渲染 HTML 块,如果你使用 JavaScript 来生成 DOM 元素,任何使用的 CSS 都会被 `hugo_stats.json` 忽略。当然你可以手动添加到 `extra_stats.json` 中,但有一个更好的方法通过模板引擎来实现。 + +1. 首先,我们需要在 `*.html` 布局定义一个模板块。 + +{{% code/purgecss-template-partial %}} + +Hugo 会将使用过的 CSS 计算到 `hugo_stats.json` 中,例如 `search-results`。 + +1. 然后通过任意的模板引擎渲染模板。 + +{{% code/purgecss-template-js %}} + +## 测试 + +你需要通过 `hugo server -e production -b http://localhost:1313` 指定 `production` 环境进行本地测试,因为 PurgeCSS 只在 `production` 环境下工作。 + +有时候,PurgeCSS 和 PostProcess 工作不是很正常,这时候你可能需要偶尔重启下 Hugo Server。 diff --git a/exampleSite/content/docs/advanced/purgecss/index.zh-hant.md b/exampleSite/content/docs/advanced/purgecss/index.zh-hant.md new file mode 100644 index 000000000..4cc47d496 --- /dev/null +++ b/exampleSite/content/docs/advanced/purgecss/index.zh-hant.md @@ -0,0 +1,71 @@ ++++ +# type = "docs" +title = "PurgeCSS" +date = 2022-07-25T12:06:00+08:00 +# description = "" # Used by description meta tag, summary will be used instead if not set or empty. +featured = false +draft = false +comment = true +toc = true +reward = true +pinned = false +carousel = false +categories = ["PurgeCSS"] +tags = [] +series = ["文檔"] +images = [] ++++ + +PurgeCSS 是一個很棒的工具,可以從你的網站上刪除未使用的 CSS。 +在本節中,我們將深入探討 PurgeCSS 是如何工作的,以及我們應該註意什麽。 + + + +## 它是如何工作的? + +PurgeCSS 需要設置以下配置。 + +{{< code-toggle filename="config" >}} +{{% config/build-write-stat %}} +{{}} + +其告訴 Hugo 計算已使用的標簽、類和 ID,然後生成`hugo_stats.json`。 + +{{% code/purgecss-hugo-stats %}} + +最後 PurgeCSS 依靠這個文件來清除未使用的 CSS。 + +> PurgeCSS 只在 `production` 環境下工作。 + +> 我們**不建議**覆蓋這些文件 `postcss.config.js` 和 `assets/main/config/rtl/postcss.config.js`,否則在版本更新中會出現意想不到的問題。 + +## 局限性 + +**`hugo_stats.json` 只適用於 `*.html` 模板**,也就是說,任何用於 JavaScript 文件的 CSS 類、標簽和 ID 仍然會被清除。 +但是不要擔心,有兩種方法可以解決這個問題。 + +### 額外的統計 + +只要在你的網站根目錄下創建一個名為 `extra_stats.json` 的文件,其形式與 `hugo_stats.json` 相同,並手動將額外的 CSS 放入其中。 + +> `extra_stats.json` 必須被提交到你的倉庫中。 + +### 將HTML塊放入 `*.html` 文件中 + +一個常見的情況是使用 JavaScript 渲染 HTML 塊,如果你使用 JavaScript 來生成 DOM 元素,任何使用的 CSS 都會被 `hugo_stats.json` 忽略。當然你可以手動添加到 `extra_stats.json` 中,但有一個更好的方法通過模板引擎來實現。 + +1. 首先,我們需要在 `*.html` 布局定義一個模板塊。 + +{{% code/purgecss-template-partial %}} + +Hugo 會將使用過的 CSS 計算到 `hugo_stats.json` 中,例如 `search-results`。 + +1. 然後通過任意的模板引擎渲染模板。 + +{{% code/purgecss-template-js %}} + +## 測試 + +你需要通過 `hugo server -e production -b http://localhost:1313` 指定 `production` 環境進行本地測試,因為 PurgeCSS 只在 `production` 環境下工作。 + +有時候,PurgeCSS 和 PostProcess 工作不是很正常,這時候你可能需要偶爾重啟下 Hugo Server。 diff --git a/exampleSite/layouts/shortcodes/code/purgecss-hugo-stats.html b/exampleSite/layouts/shortcodes/code/purgecss-hugo-stats.html new file mode 100644 index 000000000..37c1cb865 --- /dev/null +++ b/exampleSite/layouts/shortcodes/code/purgecss-hugo-stats.html @@ -0,0 +1,8 @@ +```json +{ + "htmlElements": { + "tags": [], + "classes": [], + "ids": [] +} +``` diff --git a/exampleSite/layouts/shortcodes/code/purgecss-template-js.html b/exampleSite/layouts/shortcodes/code/purgecss-template-js.html new file mode 100644 index 000000000..3f5a06727 --- /dev/null +++ b/exampleSite/layouts/shortcodes/code/purgecss-template-js.html @@ -0,0 +1,4 @@ +```js +const tmplSearchResults = document.getElementById('template-search-results').innerHTML; +render(tmplSearchResults, data); +``` diff --git a/exampleSite/layouts/shortcodes/code/purgecss-template-partial.html b/exampleSite/layouts/shortcodes/code/purgecss-template-partial.html new file mode 100644 index 000000000..00aab842d --- /dev/null +++ b/exampleSite/layouts/shortcodes/code/purgecss-template-partial.html @@ -0,0 +1,7 @@ +```html + +```