Obsidian 学习笔记

Appearance

Style Settings 主题开发进阶 ​

Style Settings 插件允许主题开发者为主题添加可视化配置界面，用户可以通过滑块、颜色选择器、下拉菜单等方式自定义主题，而无需编写 CSS。

工作原理 ​

主题 CSS（含 CSS 变量）
    ↓ Style Settings 注释标注
Style Settings 插件读取注释
    ↓ 生成配置界面
用户调整设置
    ↓ 生成 CSS 变量覆盖
主题外观实时变化

快速开始 ​

1. 在主题 CSS 中添加配置注释 ​

在你的主题 CSS 文件中，使用特殊注释格式声明配置项：

css
/* 
@settings

name: My Theme Settings
id: my-theme
description: 自定义我的主题外观
settings:

    # 颜色设置
    ## 品牌色
    accent-color:
        title: 品牌色
        description: 主题的主要强调色
        type: variable-color
        format: hex
        default: '#7c3aed'

    ## 字体设置
    font-size:
        title: 正文字号
        type: variable-number
        default: 16
        min: 12
        max: 24
        step: 1
        format: px

    # 布局设置
    content-width:
        title: 内容宽度
        type: variable-number
        default: 800
        min: 600
        max: 1200
        step: 50
        format: px

*/

2. 在 CSS 中使用变量 ​

css
body {
  --accent-color: #7c3aed;
  --font-size: 16px;
  --content-width: 800px;
}

.theme-text {
  color: var(--accent-color);
  font-size: var(--font-size);
}

.markdown-preview-view {
  max-width: var(--content-width);
  margin: 0 auto;
}

3. 用户体验 ​

用户安装 Style Settings 插件后：

  1. 打开设置 → Style Settings
  2. 找到你的主题配置面板
  3. 调整滑块、颜色、开关等
  4. 主题外观实时变化

配置类型详解 ​

颜色选择器 ​

css
/* 
primary-color:
    title: 主色
    description: 主题的主要颜色
    type: variable-color
    format: hex
    default: '#7c3aed'
    opacity: false

rgb-color:
    title: RGB 颜色
    type: variable-color
    format: rgb
    default: 'rgba(124, 58, 237, 1)'
    opacity: true
*/

数字滑块 ​

css
/*
border-radius:
    title: 圆角大小
    type: variable-number
    default: 8
    min: 0
    max: 24
    step: 1
    format: px

opacity:
    title: 透明度
    type: variable-number-slider
    default: 0.8
    min: 0
    max: 1
    step: 0.1
    format: 
*/

开关 ​

css
/*
enable-blur:
    title: 启用毛玻璃效果
    description: 为侧边栏添加毛玻璃模糊
    type: class-toggle
    default: true

compact-mode:
    title: 紧凑模式
    description: 减小间距和字号
    type: class-toggle
    default: false
*/

下拉选择 ​

css
/*
font-family:
    title: 字体选择
    type: variable-select
    default: 'system-ui'
    options:
        - system-ui
        - Georgia, serif
        - 'Courier New', monospace
        - 'Noto Sans SC', sans-serif

theme-mode:
    title: 主题模式
    type: select
    default: auto
    options:
        auto: 自动跟随系统
        light: 明亮模式
        dark: 暗色模式
*/

文本输入 ​

css
/*
custom-css:
    title: 自定义 CSS
    description: 输入自定义 CSS 代码
    type: variable-text
    default: ''

custom-font:
    title: 自定义字体名称
    type: variable-text
    default: 'Inter'
*/

高级特性 ​

分组和层级 ​

css
/*
@settings

name: My Theme
id: my-theme

settings:

    # 基础设置
        ## 颜色
            primary-color:
                title: 主色
                type: variable-color
                default: '#7c3aed'
            
            text-color:
                title: 文字颜色
                type: variable-color
                default: '#1a1a1a'
        
        ## 字体
            font-size:
                title: 字号
                type: variable-number
                default: 16
                format: px
    
    # 高级设置
        ## 布局
            content-width:
                title: 内容宽度
                type: variable-number
                default: 800
                format: px
        
        ## 效果
            enable-animations:
                title: 启用动画
                type: class-toggle
                default: true
*/

条件显示 ​

css
/*
enable-custom-font:
    title: 使用自定义字体
    type: class-toggle
    default: false

custom-font-name:
    title: 自定义字体名称
    type: variable-text
    default: 'Inter'
    condition: enable-custom-font
*/

CSS 类切换 ​

css
/*
layout-mode:
    title: 布局模式
    type: class-select
    default: default
    options:
        default: 默认布局
        compact: 紧凑布局
        wide: 宽屏布局
        zen: 禅模式
*/
css
/* CSS 中根据类名应用不同样式 */
.layout-compact .markdown-preview-view {
  font-size: 14px;
  padding: 16px;
}

.layout-wide .markdown-preview-view {
  max-width: 1200px;
}

.layout-zen .markdown-preview-view {
  max-width: 600px;
  margin: 0 auto;
  font-size: 18px;
  line-height: 1.8;
}

颜色调色板预设 ​

css
/*
color-scheme:
    title: 配色方案
    description: 选择预设配色方案
    type: class-select
    default: purple
    options:
        purple: 紫色梦幻
        blue: 海洋蓝
        green: 森林绿
        orange: 暖阳橙
        red: 热情红
*/

/* 预设配色 */
.color-purple {
  --accent-color: #7c3aed;
  --accent-light: #a78bfa;
  --accent-dark: #5b21b6;
}

.color-blue {
  --accent-color: #2563eb;
  --accent-light: #60a5fa;
  --accent-dark: #1e40af;
}

.color-green {
  --accent-color: #16a34a;
  --accent-light: #4ade80;
  --accent-dark: #15803d;
}

完整主题示例 ​

以下是一个完整的主题 Style Settings 配置：

css
/*
@settings

name: Aurora Theme Settings
id: aurora-theme
description: 自定义 Aurora 主题外观
settings:

    # 🎨 颜色配置
    
    ## 主色调
    accent-color:
        title: 品牌色
        description: 主题的主要强调色
        type: variable-color
        format: hex
        default: '#7c3aed'
        alt-format:
            - id: accent-color-rgb
              format: rgb
    
    accent-hover:
        title: 悬停色
        type: variable-color
        format: hex
        default: '#6d28d9'
    
    ## 背景色
    bg-primary:
        title: 主背景色
        type: variable-color
        format: hex
        default: '#ffffff'
    
    bg-secondary:
        title: 次背景色
        type: variable-color
        format: hex
        default: '#f8fafc'
    
    # 📝 字体配置
    
    font-size-base:
        title: 基础字号
        type: variable-number-slider
        default: 16
        min: 12
        max: 22
        step: 1
        format: px
    
    line-height:
        title: 行高
        type: variable-number-slider
        default: 1.6
        min: 1.2
        max: 2.0
        step: 0.1
    
    font-family:
        title: 字体族
        type: variable-select
        default: 'system-ui'
        options:
            - system-ui
            - 'Georgia, serif'
            - 'Inter, sans-serif'
            - 'JetBrains Mono, monospace'
    
    # 📐 布局配置
    
    content-width:
        title: 内容宽度
        type: variable-number-slider
        default: 800
        min: 600
        max: 1200
        step: 50
        format: px
    
    sidebar-width:
        title: 侧边栏宽度
        type: variable-number-slider
        default: 280
        min: 200
        max: 400
        step: 10
        format: px
    
    # ✨ 效果配置
    
    enable-blur:
        title: 毛玻璃效果
        description: 为侧边栏添加模糊背景
        type: class-toggle
        default: true
    
    enable-animations:
        title: 动画效果
        description: 启用过渡动画
        type: class-toggle
        default: true
    
    border-radius:
        title: 圆角大小
        type: variable-number-slider
        default: 8
        min: 0
        max: 20
        step: 1
        format: px
    
    shadow-intensity:
        title: 阴影强度
        type: variable-select
        default: medium
        options:
            none: 无阴影
            light: 轻微
            medium: 中等
            strong: 强烈
*/

测试与调试 ​

本地测试流程 ​

  1. 将主题 CSS 文件放入 vault/.obsidian/themes/my-theme/
  2. 安装 Style Settings 插件
  3. 在设置中切换到你的主题
  4. 打开 Style Settings 面板，确认配置项出现
  5. 调整各项设置，验证效果

调试技巧 ​

css
/* 临时调试：在 CSS 中输出当前变量值 */
body::before {
  content: "accent: " var(--accent-color) " size: " var(--font-size);
  position: fixed;
  bottom: 10px;
  right: 10px;
  background: rgba(0,0,0,0.8);
  color: white;
  padding: 4px 8px;
  font-size: 12px;
  z-index: 9999;
  font-family: monospace;
}

发布与分发 ​

主题 manifest.json ​

json
{
  "name": "Aurora",
  "version": "1.0.0",
  "minAppVersion": "1.0.0",
  "author": "Your Name",
  "authorUrl": "https://github.com/yourname",
  "fundingUrl": "https://github.com/sponsors/yourname"
}

提交到主题市场 ​

  1. 将主题提交到 obsidian-releases
  2. 在 PR 描述中注明支持 Style Settings
  3. 添加截图展示配置界面

最佳实践 ​

  1. 合理分组：使用 # 标题分组相关配置
  2. 提供默认值：所有配置项必须有合理默认值
  3. 添加描述：复杂选项需要说明文字
  4. 范围限制：数值类型设置合理的 min/max
  5. 渐进增强：效果选项默认关闭，用户按需开启
  6. 命名一致：变量名使用 --{category}-{property} 格式

相关文档 ​

相关文章

开发指南CSS 变量手册Obsidian 的 CSS 变量速查。开发指南BRAT 测试分发用 BRAT 灰度测试版开发指南破坏性变更管理API 升级时的兼容策略开发指南CI 自动发布GitHub Actions 自动构建发布