chill/menav
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
Files
2daba411ba82db697ea36c69196e674c47a0a906
menav/config
History
rbetree 2daba411ba docs: 更新重构各readme文件
2025-12-22 01:45:58 +08:00
..
_default
refactor: 修改默认配置
2025-11-09 21:58:07 +08:00
README.md
docs: 更新重构各readme文件
2025-12-22 01:45:58 +08:00

README.md

MeNav 配置目录

目录

目录概述

config 目录包含 MeNav 项目的所有配置文件，采用模块化的 YAML 格式组织。这些配置文件定义了网站的内容、结构、布局和功能，是定制个人导航站的核心。

配置目录结构

配置系统采用分层结构，清晰分离默认配置和用户配置：

config/
├── _default/           # 默认配置目录
│   ├── site.yml        # 默认网站基础配置（含导航配置）
│   └── pages/          # 默认页面配置
│       ├── home.yml    # 首页默认配置
│       ├── projects.yml
│       ├── articles.yml
│       ├── friends.yml
│       └── bookmarks.yml
└── user/               # 用户配置目录（覆盖默认配置）
    ├── site.yml        # 用户自定义网站配置（含导航配置）
    └── pages/          # 用户自定义页面配置
        ├── home.yml    # 首页用户配置
        └── ...

配置加载机制

MeNav 配置系统采用“完全替换”策略（不合并），按以下优先级选择唯一的一套配置目录：

  1. 若存在 config/user/，则只加载该目录下的配置，并完全忽略 config/_default/
  2. 否则加载 config/_default/ 作为默认配置

也就是说：config/user/ 一旦存在，就需要包含一套完整的配置（例如 site.yml 与必要的 pages/*.yml），系统不会把缺失部分从默认配置补齐。

推荐用法

为避免文档与配置字段长期不同步，建议按以下方式使用与维护：

  1. 首次使用：完整复制 config/_default/ 到 config/user/，再按需修改。
  2. 字段与结构的权威参考：
  3. 多层级嵌套书签示例：_default/pages/bookmarks-four-level.yml（2~4 层结构均有覆盖）

模块化配置文件

网站基础配置

site.yml 定义网站的基本信息和全局设置：

  • 网站标题、描述和关键词
  • 作者信息和版权声明
  • 字体配置和主题设置
  • 全局元数据和站点参数
  • 个人资料和社交媒体链接
  • 导航菜单配置（侧边栏导航项、页面标题和图标、页面顺序和可见性）

注意：从 v1.x 版本开始，导航配置已合并到 site.yml 文件中，不再使用独立的 navigation.yml 文件。如果您从旧版本迁移，请将原 navigation.yml 的内容移至 site.yml 的 navigation 字段下。

页面配置

pages/ 目录下的配置文件定义各个页面的内容：

  • home.yml: 首页分类和站点列表
  • projects.yml: 项目展示配置
  • articles.yml: 文章列表配置
  • friends.yml: 友情链接配置
  • bookmarks.yml: 书签页面配置
  • 自定义页面配置

配置详解

本章节用于补齐“怎么配才是对的”这类细节说明。为了避免示例长期过时，字段与结构的权威参考始终以默认配置为准：

site.yml 常用字段

site.yml 中字段较多，以下是常用项的解释与注意点（完整字段请以默认配置为准）：

  1. 基础信息

    • title：站点标题
    • description：站点描述（SEO/分享）
    • author：作者/署名
    • favicon、logo_text：站点图标与左上角 Logo 文本

  2. 图标模式（隐私相关）

    • icons.mode: favicon | manual
    • favicon：会请求第三方服务（Google）获取站点 favicon，失败自动回退到 Font Awesome 图标
    • manual：完全使用手动 Font Awesome 图标，不发起外部请求（适合内网/离线/隐私敏感场景）

  3. 字体

    • fonts.*.source: google | system
    • system：使用系统字体，加载更快；google：可选字体更多但可能受网络影响
    • 中文站点建议选择支持中文与字重的字体（如 Noto Sans SC）；请确保所选字体包含配置的字重，否则可能显示异常

  4. 顶部欢迎信息与社交链接

    • profile：首页顶部欢迎信息
    • social：侧边栏底部社交链接
    • profile.description 可写较长文本，用于放置个性化介绍或使用说明

  5. 导航

    • navigation[]：页面入口列表，id 需唯一，并与 pages/ 中配置文件名对应（例如 id: home 对应 pages/home.yml）
    • 只允许一个导航项 active: true 作为默认页
    • 图标使用 Font Awesome 类名字符串（例如 fas fa-home、fab fa-github）
    • 导航显示顺序与数组顺序一致，可通过调整数组顺序改变导航顺序

pages/ 页面配置

页面配置位于 pages/*.yml，每个文件对应一个页面内容，文件名与导航 id 对应：

  • pages/home.yml：首页（通常是 categories -> sites）
  • pages/projects.yml / articles.yml / friends.yml：示例页面（可按需删改）
  • pages/bookmarks.yml：书签页（通常由导入脚本生成，也可以手动维护）

提示：自定义页面时，先在 site.yml 的 navigation 中增加一个 id，再创建同名的 pages/<id>.yml。

站点描述建议简洁（例如不超过 30 个字符），以保证卡片展示更美观。

多层级嵌套配置（2-4层）

书签与分类支持 2~4 层嵌套，用于更好组织大量站点。建议直接参考默认示例：

层级命名约定（自顶向下）：

  1. categories：顶层分类
  2. subcategories：子分类
  3. groups：分组
  4. subgroups：子分组
  5. sites：站点（叶子节点）

向后兼容性

  • 原有二层结构（categories -> sites）无需修改即可继续使用
  • 系统会自动识别层级结构并匹配对应的模板/样式
  • 允许在同一份配置中混用不同层级（例如某些分类是二层，某些分类是三/四层）

配置优先级

配置项的优先级从高到低为：

  1. 用户页面配置 (user/pages/*.yml)
  2. 用户网站配置 (user/site.yml)
  3. 默认页面配置 (_default/pages/*.yml)
  4. 默认网站配置 (_default/site.yml)

配置示例

网站配置示例 (site.yml)

# 网站基本信息
title: "我的个人导航"
description: "个人收藏的网站导航页"
keywords: "导航,网址,书签,个人主页"

# 个人资料配置
profile:
  title: "个人导航站"
  subtitle: "我收藏的精选网站"
  description: "这是一个用于快速访问常用网站的个人导航页面。"

# 主题和样式设置
theme:
  default: "light"
  toggleIcon: true
  
# 字体配置
fonts:
  title: "Roboto, sans-serif"
  content: "Noto Sans SC, sans-serif"
  
# 社交媒体链接
social:
  - name: "GitHub"
    url: "https://github.com/username"
    icon: "fab fa-github"
  - name: "Twitter"
    url: "https://twitter.com/username"
    icon: "fab fa-twitter"

# 导航配置
navigation:
  - name: "首页"
    icon: "fas fa-home"
    id: "home"
    active: true
  - name: "项目"
    icon: "fas fa-project-diagram"
    id: "projects"
  - name: "文章"
    icon: "fas fa-book"
    id: "articles"

首页配置示例 (home.yml)

# 首页分类配置
categories:
  - name: "常用工具"
    icon: "fas fa-tools"
    sites:
      - name: "Google"
        url: "https://www.google.com"
        description: "全球最大的搜索引擎"
        icon: "fab fa-google"
      - name: "GitHub"
        url: "https://github.com"
        description: "代码托管平台"
        icon: "fab fa-github"
  
  - name: "学习资源"
    icon: "fas fa-graduation-cap"
    sites:
      - name: "MDN Web Docs"
        url: "https://developer.mozilla.org"
        description: "Web开发技术文档"
        icon: "fab fa-firefox-browser"

最佳实践

  1. 目录结构:

    • 总是在 user/ 目录下创建您的配置
    • 不要直接修改 _default/ 中的文件

  2. 文件命名:

    • 遵循现有的文件命名约定
    • 自定义页面配置应使用有意义的名称

  3. 配置管理:

    • 利用模块化结构分类管理配置
    • 首次使用建议先完整复制 config/_default/ 到 config/user/，再按需修改
    • 定期备份您的用户配置

  4. 配置验证:

    • 修改配置后运行 npm run check（语法检查 + 单测 + 构建）
    • 需要本地预览时运行 npm run dev（命令入口见 ../README.md#快速开始）
    • 确保 YAML 语法正确无误
Reference in New Issue View Git Blame Copy Permalink