@adamlui/scss-to-css 1.5.1 → 1.6.0

package/README.md

@@ -1,10 +1,22 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;English |
+        <a href="https://github.com/adamlui/js-utils/tree/main/scss-to-css/docs/zh-cn#readme">简体中文</a> |
+        <a href="https://github.com/adamlui/js-utils/tree/main/scss-to-css/docs/zh-tw#readme">繁體中文</a>
+    </h6>
+</div>
+
 # { } scss-to-css.js 
 
 ### Recursively compile all SCSS files into minified CSS.
 
 <a href="https://www.npmjs.com/package/@adamlui/scss-to-css"><img height=31 src="https://img.shields.io/npm/dt/%40adamlui%2Fscss-to-css?logo=npm&logoColor=white&labelColor=464646&style=for-the-badge"></a>
 <a href="#%EF%B8%8F-mit-license"><img height=31 src="https://img.shields.io/badge/License-MIT-red.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
-<a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=versions"><img height=31 src="https://img.shields.io/badge/Latest_Build-1.5.1-fc7811.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=versions"><img height=31 src="https://img.shields.io/badge/Latest_Build-1.6.0-fc7811.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
 <a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=code"><img height=31 src="https://img.shields.io/npm/unpacked-size/%40adamlui%2Fscss-to-css?style=for-the-badge&logo=ebox&logoColor=white&color=blue&labelColor=464646"></a>
 <a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:scss-to-css/scss-to-css.js"><img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Ascss-to-css%2Fscss-to-css.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=Vulnerabilities&color=gold"></a>
 
@@ -18,12 +30,19 @@ As a **global utility**:
 npm install -g @adamlui/scss-to-css
 ```
 
-As a **dev dependency**, from your project root:
+As a **dev dependency** (e.g. for build scripts):
 
 ```
 npm install -D @adamlui/scss-to-css
 ```
 
+
+As a **runtime dependency** (e.g. for on-the-fly compilation):
+
+```
+npm install @adamlui/scss-to-css
+```
+
 ## 💻 Usage
 
 The basic **global command** is:
@@ -32,13 +51,11 @@ The basic **global command** is:
 scss-to-css
 ```
 
-**💡 Note:** Pass `-n` or `--dry-run` to only see what files will be processed.
-
 Sample output:
 
 <img src="https://github.com/adamlui/js-utils/blob/main/scss-to-css/media/images/sample-output.png">
 
-**💡 Note:** Source maps are also generated by default unless `-S` or `--disable-source-maps` is passed.
+**💡 Note:** Source maps are also generated by default unless `-S` or `--no-source-maps` is passed.
 
 #
 
@@ -48,10 +65,10 @@ To specify **input/output** paths:
 scss-to-css [input_path] [output_path]
 ```
 
-- `[input_path]`: Path to SCSS file or directory containing SCSS files to be compiled, relative to the current working directory. 
-- `[output_path]`: Path to file or directory where CSS + sourcemap files will be stored, relative to original file location (if not provided, `css/` is used).
+- `[input_path]`: Path to SCSS file or directory containing SCSS files to be compiled, relative to the current working directory.
+- `[output_path]`: Path to file or directory where CSS + source map files will be stored, relative to original file location (if not provided, `css/` is used).
 
-**💡 Note:** If folders are passed, files will be processed recursively. To include dotfolders, pass `-d` or `--include-dotfolders`.
+**💡 Note:** If folders are passed, files will be processed recursively unless `-R` or `--no-recursion` is passed.
 
 #
 
@@ -66,35 +83,130 @@ To use as a **package script**, in your project's `package.json`:
 Replace `<scss-to-css-cmd>` with `scss-to-css` + optional args. Then, `npm run build:css` can be used to run the command.
 <br><br>
 
-## 📃 Example commands:
+### Example commands
 
-- Compile all SCSS files in the **current directory** (outputs to `css/`):
+Compile all SCSS files in the **current directory** (outputs to `css/`):
 
-   ```
-   scss-to-css
-   ```
+```
+scss-to-css
+```
 
-- Compile all SCSS files in a **specific directory** (outputs to `path/to/your/directory/css/`):
+Compile all SCSS files in a **specific directory** (outputs to `path/to/your/directory/css/`):
 
-   ```
-   scss-to-css path/to/your/directory
-   ```
+```
+scss-to-css path/to/your/directory
+```
 
-- Compile a **specific file** (outputs to `path/to/your/css/file.min.css`):
+Compile a **specific file** (outputs to `path/to/your/css/file.min.css`):
 
-   ```
-   scss-to-css path/to/your/file.scss
-   ```
+```
+scss-to-css path/to/your/file.scss
+```
 
-- Specify both **input and output** directories (outputs to `output_folder/`):
+Specify both **input and output** directories (outputs to `output_folder/`):
 
-   ```
-   scss-to-css input_folder output_folder
-   ```
+```
+scss-to-css input_folder output_folder
+```
 
 **💡 Note:** Output CSS is minified unless `-M` or `--no-minify` is passed.
 <br><br>
 
+### Command line options
+
+```
+Config options:
+ -n, --dry-run               Don't actually compile the file(s), just
+                             show if they will be processed.
+ -d, --include-dotfolders    Include dotfolders in file search.
+ -S, --no-source-maps        Prevent source maps from being generated.
+ -M, --no-minify             Disable minification of output CSS.
+ -R, --no-recursion          Disable recursive file searching.
+ -q, --quiet                 Suppress all logging except errors.
+
+Info commands:
+ -h, --help                  Display this help screen.
+ -v, --version               Show version number.
+```
+
+## 🔌 API reference
+
+You can also import **scss-to-css** into your app to use its API methods, both as an ECMAScript module or a CommonJS module.
+
+#### ESM:
+
+```js
+import * as scssToCSS from '@adamlui/scss-to-css';
+```
+
+#### CJS:
+
+```js
+const scssToCSS = require('@adamlui/scss-to-css');
+```
+
+### compile(inputPath, options)
+
+This function compiles SCSS found in the `inputPath` provided into CSS data.
+
+If a **file path** is passed, the file's code is compiled to CSS, then an object containing `srcPath` + `code` + `error` is returned:
+
+```js
+const compileResult = scssToCSS.compile('assets/style.scss');
+console.log(compileResult.error); // runtime error, or `undefined` if no error
+console.log(compileResult.code);  // compiled CSS output of assets/style.scss
+```
+
+If a **directory path** is passed, SCSS files are searched for (recursively by default), each one's code is loaded then compiled, then an array of objects containing `srcPath` + `code` + `error` is returned:
+
+```js
+const results = scssToCSS.compile('.');
+results.forEach(result =>
+    console.log(result.srcPath) // paths to SCSS files in working directory + all nested directories
+);
+console.log(results[1].code); // compiled CSS output of 2nd SCSS file if found, or `undefined` if not found
+```
+
+Options are boolean, passed as object properties. For example:
+
+```js
+scssToCSS.compile(inputDir, { minify: false });
+// returns data objects where `.code` contains unminified CSS
+```
+
+Possible parameters (and their default settings) are:
+
+```
+ recursive (true)     Recursively search for nested files if dir path
+                      passed.
+ verbose (true)       Show logging in console/terminal.
+ dotFolders (false)   Include dotfolders in file search.
+ minify (true)        Minify output CSS.
+ sourceMaps (true)    Generate CSS source maps.
+```
+
+### findSCSS(searchDir, options)
+
+This function searches for all SCSS files within the `searchDir` string passed (useful for discovering what files [`compile()`](#compileinputpath-options) will process) and returns an array containing their filepaths.
+
+Options are boolean, passed as object properties. For example:
+
+```js
+scssToCSS.findSCSS(searchDir, { recursive: false });
+// returns array containing filepaths to SCSS files in exactly `searchDir`
+```
+
+Possible parameters (and their default settings) are:
+
+```
+ recursive (true)     Recursively search for nested files if dir path
+                      passed.
+ verbose (false)      Show logging in console/terminal.
+ dotFolders (false)   Include dotfolders in file search.
+```
+
+<br>
+
 ## 💖 Support
 
 Please consider [giving a GitHub ⭐](https://github.com/adamlui/js-utils) if this helped you!
@@ -102,25 +214,13 @@ Please consider [giving a GitHub ⭐](https://github.com/adamlui/js-utils) if th
 
 ## 🏛️ MIT License
 
-**Copyright (c) 2024 [Adam Lui](https://github.com/adamlui)**
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+**Copyright © 2024 [Adam Lui](https://github.com/adamlui)**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 <br>
 

package/docs/LICENSE.md

@@ -1,9 +1,21 @@
-# 🏛️ MIT License
-
-**Copyright (c) 2024 [Adam Lui](https://github.com/adamlui)**
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;English |
+        <a href="zh-cn/LICENSE.md">简体中文</a> |
+        <a href="zh-tw/LICENSE.md">繁體中文</a>
+    </h6>
+</div>
+
+# 🏛️ MIT License
+
+**Copyright © 2024 [Adam Lui](https://github.com/adamlui)**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/docs/SECURITY.md

@@ -1,5 +1,17 @@
-# 🛡️ Security Policy
-
-If you find a vulnerability, please open a [draft security advisory](https://github.com/adamlui/js-utils/security/advisories/new).
-
-Pull requests are also welcome, but for safety reasons, send an email to <adam@kudoai.com> and wait for a response before making it public.
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;English |
+        <a href="zh-cn/SECURITY.md">简体中文</a> |
+        <a href="zh-tw/SECURITY.md">繁體中文</a>
+    </h6>
+</div>
+
+# 🛡️ Security Policy
+
+If you find a vulnerability, please open a [draft security advisory](https://github.com/adamlui/js-utils/security/advisories/new).
+
+Pull requests are also welcome, but for safety reasons, send an email to <adam@kudoai.com> and wait for a response before making it public.

package/docs/zh-cn/LICENSE.md

@@ -0,0 +1,21 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;简体中文 |
+        <a href="../LICENSE.md">English</a> |
+        <a href="../zh-tw/LICENSE.md">繁體中文</a> 
+    </h6>
+</div>
+
+# 🏛️ MIT 许可证
+
+**版权所有 © 2023–2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+
+特此免费向任何获得副本的人授予许可本软件和相关文档文件（『软件』），处理在软件中不受限制，包括但不限于权利使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，并允许该软件是提供这样做，但须满足以下条件：
+
+上述版权声明和本许可声明应包含在所有软件的副本或重要部分。
+
+本软件『按原样』提供，不提供任何形式的明示或保证暗示的，包括但不限于适销性保证，适用于特定目的和非侵权。 在任何情况下都不得作者或版权持有人对任何索赔、损害或其他责任，无论是在合同、侵权或其他方面的行为中，由以下原因引起，出于或与软件或使用或其他交易有关软件。

package/docs/zh-cn/README.md

@@ -0,0 +1,228 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;简体中文 |
+        <a href="../..#readme">English</a> |
+        <a href="../zh-tw#readme">繁體中文</a>
+    </h6>
+</div>
+
+# { } scss-to-css.js 
+
+### 将所有 SCSS 文件递归编译为缩小的 CSS。
+
+<a href="https://www.npmjs.com/package/@adamlui/scss-to-css"><img height=31 src="https://img.shields.io/npm/dt/%40adamlui%2Fscss-to-css?label=%E4%B8%8B%E8%BD%BD&logo=npm&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="#%EF%B8%8F-mit-%E8%AE%B8%E5%8F%AF%E8%AF%81"><img height=31 src="https://img.shields.io/badge/许可证-MIT-red.svg?logo=internetarchive&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=versions"><img height=31 src="https://img.shields.io/badge/最新版本-1.6.0-fc7811.svg?logo=icinga&logoColor=white&labelColor=464646&style=for-the-badge"></a>
+<a href="https://www.npmjs.com/package/@adamlui/scss-to-css?activeTab=code"><img height=31 src="https://img.shields.io/npm/unpacked-size/%40adamlui%2Fscss-to-css?label=%E6%8B%86%E5%B0%81%E5%B0%BA%E5%AF%B8&style=for-the-badge&logo=ebox&logoColor=white&color=blue&labelColor=464646"></a>
+<a href="https://sonarcloud.io/component_measures?metric=new_vulnerabilities&id=adamlui_js-utils:scss-to-css/scss-to-css.js"><img height=31 src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fsonarcloud.io%2Fapi%2Fmeasures%2Fcomponent%3Fcomponent%3Dadamlui_js-utils%3Ascss-to-css%2Fscss-to-css.js%26metricKeys%3Dvulnerabilities&query=%24.component.measures.0.value&style=for-the-badge&logo=sonarcloud&logoColor=white&labelColor=464646&label=%E6%BC%8F%E6%B4%9E&color=gold"></a>
+
+<img height=8px width="100%" src="https://github.com/adamlui/js-utils/blob/main/docs/images/aqua-separator.png">
+
+## ⚡ 如何安装
+
+作为**全局实用程序**：
+
+```
+npm install -g @adamlui/scss-to-css
+```
+
+作为**开发人员依赖**（例如，对于构建脚本）：
+
+```
+npm install -D @adamlui/scss-to-css
+```
+
+
+作为**运行时依赖**（例如，用于动态编译）：
+
+```
+npm install @adamlui/scss-to-css
+```
+
+## 💻 命令行使用
+
+基本的**全局命令**是：
+
+```
+scss-to-css
+```
+
+示例输出：
+
+<img src="https://github.com/adamlui/js-utils/blob/main/scss-to-css/media/images/sample-output.png">
+
+**💡 笔记：** 默认情况下也会生成源映射，除非传递 `-S` 或 `--no-source-maps`。
+
+#
+
+指定**输入/输出**路径：
+   
+```
+scss-to-css [input_path] [output_path]
+```
+
+- `[input_path]`: SCSS 文件或包含要编译的 SCSS 文件的目录的路径，相对于当前工作目录。
+- `[output_path]`: 将存储 CSS + 源映射文件的文件或目录的路径，相对于原始文件位置（如果未提供，则使用 `css/`）。
+
+**💡 注意：** 如果传递文件夹，文件将被递归处理，除非传递 `-R` 或 `--no-recursion`。
+
+#
+
+要用作 **包脚本**，请在项目的 `package.json` 中：
+
+```json
+  "scripts": {
+    "build:css": "<scss-to-css-cmd>"
+  },
+```
+
+将 `<scss-to-css-cmd>` 替换为 `scss-to-css` + 可选参数。 然后，可以使用 `npm run build:css` 来运行该命令。
+<br><br>
+
+### 命令示例
+
+编译 **当前目录** 中的所有 SCSS 文件（输出到 `css/`）：
+
+```
+scss-to-css
+```
+
+编译 **特定目录** 中的所有 SCSS 文件（输出到 `path/to/your/directory/css/`）：
+
+```
+scss-to-css path/to/your/directory
+```
+
+编译一个**特定文件**（输出到 `path/to/your/css/file.min.css`）：
+
+```
+scss-to-css path/to/your/file.scss
+```
+
+指定 **输入和输出** 目录（输出到 `output_folder/`）：
+
+```
+scss-to-css input_folder output_folder
+```
+
+**💡 注意：** 除非传递 `-M` 或 `--no-minify` ，否则输出 CSS 会被缩小。
+<br><br>
+
+### 命令行选项
+
+```
+配置选项：
+ -n, --dry-run               实际上并不缩小文件，只是显示它们是否会被处理。
+ -d, --include-dotfolders    在文件搜索中包括点文件夹。
+ -S, --no-source-maps        防止生成源映射。
+ -M, --no-minify             禁用输出 CSS 的缩小。
+ -R, --no-recursion          禁用递归文件搜索。
+ -q, --quiet                 禁止除错误之外的所有日志记录。
+
+信息命令：
+ -h, --help                  显示帮助屏幕。
+ -v, --version               显示版本号。
+```
+
+## 🔌 API 参考
+
+您还可以将 **scss-to-css** 导入您的应用程序以使用其 API 方法，无论是作为 ECMAScript 模块还是 CommonJS 模块。
+
+#### ESM:
+
+```js
+import * as scssToCSS from '@adamlui/scss-to-css';
+```
+
+#### CJS:
+
+```js
+const scssToCSS = require('@adamlui/scss-to-css');
+```
+
+### compile(inputPath, options)
+
+此函数将在 `inputPath` 中找到的 SCSS 编译为 CSS 数据。
+
+如果传递 **文件路径**，则文件的代码将编译为 CSS，然后返回一个包含 `srcPath` + `code` + `error` 的对象：
+
+```js
+const compileResult = scssToCSS.compile('assets/style.scss');
+console.log(compileResult.error); // 运行时错误，如果没有错误则为 `undefined`
+console.log(compileResult.code);  // 编译后的 assets/style.scss CSS 输出
+```
+
+如果传递 **目录路径**，则搜索 SCSS 文件（默认情况下递归），加载每个文件的代码并编译，然后返回包含 `srcPath` + `code` + `error` 的对象数组：
+
+```js
+const results = scssToCSS.compile('.');
+results.forEach(result =>
+    console.log(result.srcPath) // 工作目录 + 所有嵌套目录中 SCSS 文件的路径
+);
+console.log(results[1].code); // 如果找到，则编译第二个 SCSS 文件的 CSS 输出，如果未找到，则为 `undefined`
+```
+
+选项是布尔值，作为对象属性传递。 例如：
+
+```js
+scssToCSS.compile(inputDir, { minify: false });
+// 返回 `.code` 包含未缩小 CSS 的数据对象
+```
+
+可能的参数（及其默认设置）有：
+
+```
+ recursive (true)     如果传递目录路径，则递归搜索嵌套文件。
+ verbose (true)       在控制台/终端中显示日志记录。
+ dotFolders (false)   在文件搜索中包括点文件夹。
+ minify (true)        缩小输出 CSS。
+ sourceMaps (true)    生成 CSS 源映射。
+```
+
+### findSCSS(searchDir, options)
+
+此函数搜索传递的 `searchDir` 字符串中的所有 SCSS 文件（对于发现 [`compile()`](#compileinputpath-options) 将处理哪些文件很有用）并返回包含其文件路径的数组。
+
+选项是布尔值，作为对象属性传递。 例如：
+
+```js
+scssToCSS.findSCSS(searchDir, { recursive: false });
+// 返回包含恰好位于 `searchDir` 中的 SCSS 文件的文件路径的数组
+```
+
+可能的参数（及其默认设置）有：
+
+```
+ recursive (true)     如果传递目录路径，则递归搜索嵌套文件。
+ verbose (false)      在控制台/终端中显示日志记录。
+ dotFolders (false)   在文件搜索中包括点文件夹。
+```
+
+<br>
+
+## 💖 支持
+
+如果这对您有帮助，请考虑[给予 GitHub ⭐](https://github.com/adamlui/js-utils)！
+<br><br>
+
+## 🏛️ MIT 许可证
+
+**版权所有 © 2023–2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+
+特此免费向任何获得副本的人授予许可本软件和相关文档文件（『软件』），处理在软件中不受限制，包括但不限于权利使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，并允许该软件是提供这样做，但须满足以下条件：
+
+上述版权声明和本许可声明应包含在所有软件的副本或重要部分。
+
+本软件『按原样』提供，不提供任何形式的明示或保证暗示的，包括但不限于适销性保证，适用于特定目的和非侵权。 在任何情况下都不得作者或版权持有人对任何索赔、损害或其他责任，无论是在合同、侵权或其他方面的行为中，由以下原因引起，出于或与软件或使用或其他交易有关软件。
+
+<br>
+
+<img height=6px width="100%" src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/aqua-separator.png">
+
+<a href="https://github.com/adamlui/js-utils">**家**</a> /
+<a href="https://github.com/adamlui/js-utils/discussions">讨论</a> /
+<a href="#--scss-to-css">回到顶部 ↑</a>

package/docs/zh-cn/SECURITY.md

@@ -0,0 +1,17 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;简体中文 |
+        <a href="../SECURITY.md">English</a> |
+        <a href="../zh-tw/SECURITY.md">繁體中文</a>
+    </h6>
+</div>
+
+# 🛡️ 安全政策
+
+如果您发现漏洞，请打开[安全公告草案](https://github.com/adamlui/js-utils/security/advisories/new)。
+
+也欢迎拉取请求，但出于安全原因，请发送电子邮件至 <adam@kudoai.com> 并等待回复后再公开。

package/docs/zh-tw/LICENSE.md

@@ -0,0 +1,21 @@
+<div align="right">
+    <h6>
+        <picture>
+            <source type="image/svg+xml" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/white/icon32.svg">
+            <img height=14 src="https://raw.githubusercontent.com/adamlui/js-utils/main/docs/images/earth-icon/black/icon32.svg">
+        </picture>
+        &nbsp;繁體中文 |
+        <a href="../LICENSE.md">English</a> |
+        <a href="../zh-cn/LICENSE.md">简体中文</a>
+    </h6>
+</div>
+
+# 🏛️ MIT 许可证
+
+**版權所有 © 2023–2024 [刘展鹏 (Adam Lui)](https://github.com/adamlui)**
+
+特此免費授予任何取得副本的人許可本軟體和相關文件文件（『軟體』），處理在軟體中不受限制，包括但不限於權利使用、複製、修改、合併、發布、分發、再授權和/或出售該軟體的副本，並允許該軟體是提供這樣做，但須滿足以下條件：
+
+上述版權聲明和本許可聲明應包含在所有軟體的副本或重要部分。
+
+本軟體『依現況』提供，不提供任何形式的明示或保證暗示的，包括但不限於適銷性保證，適用於特定目的和非侵權。 在任何情況下都不得作者或版權持有人對任何索賠、損害或其他責任，無論是在合約、侵權或其他方面的行為中，由以下原因引起，出於或與軟體或使用或其他交易有關軟體。