更多关于 Quarto 主题的内容

作为 Quarto 的一部分，我们开发了一种简单的单文件格式，用于描述在将 Scss 文件编译为 css 时应该分层导入的声明、变量和规则。主题文件的基本结构如下：

一个包含有效 Scss 代码的文本文件
使用特殊注释来标记函数、默认值、混合器和规则的区域（区域装饰器）。
主题文件必须至少包含一个区域装饰器才能有效。
允许存在多个相同类型的区域装饰器。如果存在多个相同类型的区域装饰器，所有该类型的区域将按其在文件中出现的顺序合并为一个该类型的单一区块。
编译时，各部分将按类型分层，首先是函数，然后是变量，接着是混合器，最后是规则。
包含主题文件的目录将被添加到加载路径中，允许使用 @use 或 @import 语句解析与主题文件位于同一目录的文件。

以下是一个示例文件：

/*-- scss:functions --*/
@function colorToRGB ($color) {
  @return "rgb(" + red($color) + ", " + green($color) + ", " + blue($color)+ ")";
}

/*-- scss:defaults --*/
$h2-font-size:          1.6rem !default;
$headings-font-weight:  500 !default;

/*-- scss:rules --*/
h1, h2, h3, h4, h5, h6 {
  text-shadow: -1px -1px 0 rgba(0, 0, 0, .3);
}

Bootswatch Sass 主题文件

我们已将适用于 Bootstrap 5 的 Bootswatch 主题合并为此单文件主题格式，并存放于我们的仓库中：

https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/html/bootstrap/themes

随着 Bootswatch 主题的更新，我们将不时更新这些合并的主题文件。

Bootstrap / Bootswatch 分层

在使用 Quarto HTML 格式时，我们允许用户在文档前言（或项目 YAML）中指定主题信息。主题信息由以下一项或多项组成：

一个有效的内置 Bootswatch 主题名称
一个主题文件（如上所述有效）。

例如，以下内容将使用 cosmo Bootswatch 主题，并使用 custom.scss 文件进行自定义：

theme:
  - cosmo
  - custom.scss

在编译 Quarto 网站或 HTML 页面的 CSS 时，我们将用户提供的任何主题文件或 Bootswatch 主题与 Bootstrap Scss 按以下层次合并：

Uses
    Bootstrap
    Theme(s)       /*-- scss:uses --*/
    
Functions
    Bootstrap
    Theme(s)       /*-- scss:functions --*/

Variables
    Themes(s)      /*-- scss:defaults --*/
    Bootstrap
    
Mixins                 
    Bootstrap
    Theme(s)       /* -- scss:mixins --*/

Rules
    Bootstrap
    Theme(s)       /*-- scss:rules --*/

我们按照 YAML 中指定的顺序排列主题，保持声明和规则的顺序，变量的顺序则相反（允许列表中较后的文件为列表中较前的文件提供默认变量值）。上述示例主题的分层如下：

Uses
    Bootstrap
    cosmo           /*-- scss:uses --*/
    custom.scss     /*-- scss:uses --*/

Functions
    Bootstrap
    cosmo           /*-- scss:functions --*/
    custom.scss     /*-- scss:functions --*/

Variables
    custom.scss     /*-- scss:defaults --*/
    cosmo           /*-- scss:defaults --*/
    Bootstrap

Mixins
    Bootstrap
    cosmo            /* -- scss:mixins --*/
    custom.scss      /* -- scss:mixins --*/

Rules
    Bootstrap
    cosmo           /*-- scss:rules --*/
    custom.scss     /*-- scss:rules --*/