配置文件

配置文件可以添加设置网站内容和主题等。

添加配置

目前有三种配置，每种配置方式都起不通的作用，都不是必要的配置，配置格式均使用 yaml。三种配置：

idoc.yml

在你的配置最顶端添加配置 schema，进行数据有效性的验证，方便排出您的配置错误问题，如果你是 Visual Studio Code 需要按照 YAML 插件支持这一特性。

# yaml-language-server: $schema=https://jaywcjlove.github.io/idoc/schema
# yaml-language-server: $schema=https://jaywcjlove.gitee.io/idoc/schema

下面是 idoc.yml 完整示例：

# yaml-language-server: $schema=https://jaywcjlove.github.io/idoc/schema
# yaml-language-server: $schema=https://jaywcjlove.gitee.io/idoc/schema

## directory of document source files
## defalut: `docs`
# -----------------------
dir: docs

## output directory of generated documents
## defalut: `dist`
# -----------------------
output: dist

## site name
# -----------------------
site: iDoc

## Customize theme settings.
## defalut: `default`
# -----------------------
theme: default


## Website logo icon
## defalut: `data:image/png;base64,iVBOR......`
# -----------------------
logo: ./logo.png


## Website favicon icon
## defalut: `data:image/png;base64,iVBOR......`
# -----------------------
favicon: ./logo.png


## Template Data
# -----------------------
data: 
  # Show open source button
  openSource: https://github.com/jaywcjlove/idoc
  # Display the edit button, need to configure `openSource`.
  editButton: 
    label: Edit this page on GitHub
    url: https://github.com/jaywcjlove/idoc/blob/master/
  # Navigation Menu.
  menus:
    # Label: <URL> [scope]
    Docs: introduce/getting-started/installation.html introduce
    Markdown: markdown.html
    About: about.html

  footer: |
    Released under the MIT License. Copyright © 2022 Kenny Wong<br />
    Generated by <a href="https://github.com/jaywcjlove/idoc" target="_blank">idoc</a>

dir

文档（markdown）所在的目录，默认配置当前项目根目录下的 docs 文件夹中。

output

文档（markdown）输出的 HTML 所在的目录，默认配置当前项目根目录下的 dist 文件夹中。

site

自定义网站的名称，也将用户导航菜单 logo 旁边显示的文本。

description

对网页的一个简单概述，默认获取当前 Markdown 页面第一段文本。

keywords

搜索引擎能搜索到的关键词，每个关键词之间用逗号，隔开，必须是英文的逗号。idoc.yml -> 注释配置

keywords: idoc,document,doc

自定义网站的导航菜单 logo，默认内置了 logo。

favicon

自定义网站的 favicon 图标，默认内置了图标。

site: iDoc

如果你没有配置，将会自动读取 package.json 中的 name 字段

{
  "name": "idoc",
}

theme

主题定制，默认值为 default，你也可以自定义主题，可以使用 idoc init myapp 生成项目工程的时候，选择暴露模版文件，主题将被生成到 themes/default 目录中

## Customize theme settings.
## defalut: `default`
# -----------------------
theme: themes/default

openSource

默认页面顶部 GitHub 按钮菜单自定义。

openSource: https://github.com/jaywcjlove/idoc

如果你没有配置，将会自动读取 package.json 中的 repository 字段

"repository": {
  "type": "git",
  "url": "https://github.com/jaywcjlove/idoc.git"
},

editButton

默认页面 编辑按钮 定义。

editButton: 
  label: Edit this page on GitHub
  url: https://github.com/jaywcjlove/idoc/blob/master/

默认主题顶部导航菜单定义

menus:
  # Label: <URL> [scope]
  Docs: introduce/getting-started/installation.html introduce
  Markdown: markdown.html
  About: about.html

定义范围 scope，下面示例定义了个范围名字叫 introduce，这个范围表示，匹配到 introduce 开头的页面，页面导航 Docs 选中效果。

menus:
  # Label: <URL> [scope]
  Docs: introduce/getting-started/installation.html introduce

🚧 注意：这个 scope 范围，如果没有任何菜单定义 scope 范围，将在所有页面展示一样的 SiderBar 左侧边菜单栏。如果你定义了 scope，根据你定义的范围(scope) 在匹配页面路由，将在侧边栏展示不同的 SiderBar。SiderBar 需要在 idoc.chapters.yml 中定义，并且需要在 idoc.yml 中定义 menus。

页脚自定义。

footer: |
  Released under the MIT License. Copyright © 2022 Kenny Wong<br />
  Generated by <a href="https://github.com/jaywcjlove/idoc" target="_blank">idoc</a>

data

默认主题模版变量传递，这将对自定义主题可能会起到很大的帮助。除了以上定义，定义多余的变量也会被传递到模板中。

data:
  name: value

目前保留这个配置作用是，如果配置使用了 schema，传递的变量放到 data 配置(idoc.yml)不会报错 :)，还有避免覆盖内置变量。

idoc.chapters.yml

定义左侧边栏(SiderBar)菜单，同时可以控制顺序，可以在 idoc.yml 配置中定义 scope，顶部一级导航根据匹配 scope 来展示不同的 (SiderBar)菜单。

- introduce/getting-started: 入门
- introduce/getting-started/installation.md: 安装
- introduce/getting-started/publish.md: 发布网站
- introduce/getting-started/site-creation.md: 创建网站
- introduce/getting-started/site-preparation.md: 网站准备
- introduce/api: API
- introduce/api/command.md: 命令
- introduce/api/config.md: 配置文件说明

注释配置

这种配置是指在 markdown 文档中添加的配置，主要用于控制类似于 tocs 页面导航是否显示，页面标题展示，翻页等功能。在 markdown 注释配置所在的页面起作用。

配置方法

在 markdown 文本中，任意位置添加一条特定标记(<!--idoc:config:<您的配置>-->)的注视，将 yaml 格式的配置添加到注释中即可：

<!--idoc:config:
tocs: false
site: 网站名称
-->

详细配置说明

🚧 注意：注释配置将覆盖全局配置。

# 页面目录隐藏
tocs: false
# 当前页面网站名称，可以全局 `idoc.yml` 中配置
# 🚧 Logo 旁边的 <网站名称>，和 <title> 的名称配置
# 可以全局 `idoc.yml` 中配置，
# 都没有配置在 `package.json` 中读取 `name` 字段信息
site: 网站名称
# 在浏览器标签处显示的内容
# 默认 Markdown 文档第一个标题 <h1>
title: 网页标题
# 对网页的一个简单概述，默认获取当前 Markdown 页面第一段文本
description: 网页简述
# 搜索引擎能搜索到的关键词，每个关键词之间用逗号，隔开，必须是英文的逗号。
keywords: 关键词
# 显示编辑按钮
editButton: 
  label: Edit this page on GitHub
  url: https://github.com/jaywcjlove/idoc/blob/master/
# 导航栏 GitHub 按钮
openSource: https://github.com/jaywcjlove/idoc
# 当前页面<页脚>配置
footer: |
  Released under the MIT License. Copyright © 2022 Kenny Wong<br />
  Generated by <a href="https://github.com/jaywcjlove/idoc" target="_blank">idoc</a>
# 🚧 当前文件信息，不准确，比如 CI 在服务端生成，没有办法记录 修改时间。
fileStat:
  # 配置当前文档的修改时间，展示在页脚
  mtimeStr: 2022/04/13

layout

布局模版配置，默认值 markdown.ejs 不需要配置，这将在您自定义模板的时候很有用，例如您需要自定义首页。

layout: markdown.ejs

🚧 注意：默认不需要配置，自定义主题的时候可以用得到。
Released under the MIT License. Copyright © 2022 Kenny Wong
Generated by idoc