配置文件可以添加设置网站内容和主题等。
目前有三种配置,每种配置方式都起不通的作用,都不是必要的配置,配置格式均使用 yaml。三种配置:
idoc.yml
在根目录下添加(可选配置)。idoc.chapters.yml
左侧栏文件导航(SiderBar),在根目录下添加(可选配置)。注释配置
在 markdown 文档中添加的配置(可选配置)。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
## Page title
# -----------------------
title: Config page iDoc
## Site description
# -----------------------
description: Website description
## The keywords of your website.
# -----------------------
keywords: idoc,document,doc
## 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
# 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/
## chapters scopes
# -----------------------
# scope:
# - introduce
# Navigation Menu.
menus:
# Label: <URL> [scope]
Docs: introduce/getting-started/installation.html introduce
Markdown: markdown.html
About: about.html
Github:
url: https://github.com/jaywcjlove/idoc
target: __blank
footer: |
Released under the MIT License. Copyright © 2022 Kenny Wong<br />
Generated by <a href="https://github.com/jaywcjlove/idoc" target="_blank">idoc</a> v{{idocVersion}}
## Template Data
# -----------------------
data:
good: test
dir
文档(markdown)所在的目录,默认配置当前项目根目录下的 docs
文件夹中。
output
文档(markdown)输出的 HTML 所在的目录,默认配置当前项目根目录下的 dist
文件夹中。
site
自定义网站的名称,也将用户导航菜单 logo 旁边显示的文本。
site: iDoc
如果你没有配置,将会自动读取 package.json
中的 name
-> title
字段,优先 title
字段。
{
"name": "idoc",
"title": "idoc book",
}
description
对网页的一个简单概述,默认获取当前 Markdown 页面第一段文本。
description: idoc description
如果你没有配置,将会自动读取 package.json
中的 description
字段
{
"description": "idoc description",
}
keywords
搜索引擎能搜索到的关键词,每个关键词之间用英文逗号 ,
隔开,必须是英文的逗号。package.json
-> idoc.yml
-> 注释配置
keywords: idoc,markdown,api,document,tool
如果你没有配置,将会自动读取 package.json
中的 keywords
字段
{
"keywords": [
"idoc",
"markdown",
"api",
"document",
"tool"
]
}
keywords: idoc,document,doc
tocs
全局配置,隐藏所有的页面目录。
tocs: false
logo
自定义网站的导航菜单 logo
,默认内置了 logo
。
## Website logo icon
## defalut: `data:image/png;base64,iVBOR......`
# -----------------------
logo: ./logo.png
支持 base64 字符串,和图片文件相对目录配置,如果配置 svg 图标路径,自动将 svg 代码生成到页面中,这将有助于解决明暗主题样式、logo 模糊等问题。
favicon
自定义网站的 favicon
图标,默认内置了图标。
## Website favicon icon
## defalut: `data:image/png;base64,iVBOR......`
# -----------------------
favicon: ./logo.png
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/
scope
scope:
- introduce/getting-started
与在 menus
中定义 scope
效果是一样的
menus:
Docs: introduce/getting-started/installation.html
Markdown: markdown/basic-syntax.html markdown
menus
默认主题顶部导航菜单定义
menus:
# Label: <URL> [scope]
Docs: introduce/getting-started/installation.html introduce
Markdown: markdown.html
About: about.html
Github:
url: https://github.com/jaywcjlove/idoc
target: __blank
定义范围 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
页脚自定义。
footer: |
Released under the MIT License. Copyright © 2022 Kenny Wong<br />
Generated by <a href="https://github.com/jaywcjlove/idoc" target="_blank">idoc</a> v{{idocVersion}}
这里预留了 {{idocVersion}}
和 {{version}}
两个字符串,用于替换 idoc 当前的版本,或者项目 package.json
中的版本信息。
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: 关键词
# 自定义网站的 favicon 图标,默认内置了图标。
favicon: page.favicon || config.data.favicon,
# 自定义网站的导航菜单 logo,默认内置了 logo。
logo: page.logo || config.data.logo,
# 显示编辑按钮
editButton:
label: Edit this page on GitHub
url: https://github.com/jaywcjlove/idoc/blob/master/
# 导航栏 GitHub 按钮
openSource: https://github.com/jaywcjlove/idoc
# 🚧 翻页默认不需要配置,默认是根据 `idoc.chapters.yml` 的顺序自动生成。
# 👈 上一页,raw 配置指定目录(默认 docs)全路径,idoc 会处理成正确的目录。
prevPage:
raw: introduce/getting-started/site-add.md
label: 添加文档 # 🤙 可以单独只配 label 覆盖默认的 label
# 🚧 翻页默认不需要配置,默认是根据 `idoc.chapters.yml` 的顺序自动生成。
# 👉 下一页,raw 配置指定目录(默认 docs)全路径,idoc 会处理成正确的目录
nextPage:
raw: introduce/getting-started/site-add.md
label: 添加文档 # 🤙 可以单独只配 label 覆盖默认的 label
# 当前页面<页脚>配置
footer: |
Released under the MIT License. Copyright © 2022 Kenny Wong<br />
Generated by <a href="https://github.com/jaywcjlove/idoc" target="_blank">idoc</a> v{{idocVersion}}
# 🚧 当前文件信息,不准确,比如 CI 在服务端生成,没有办法记录 修改时间。
fileStat:
# 配置当前文档的修改时间,展示在页脚
mtimeStr: 2022/04/13
如果全局配置,隐藏所有的页面目录,在页面中注释配置 tocs=true
,让某个页面显示页面目录。
<!--idoc:config:
tocs: true
-->
布局模版配置,默认值 markdown.ejs
不需要配置,这将在您自定义模板的时候很有用,例如您需要自定义首页。
<!--idoc:config:
layout: markdown.ejs
-->
🚧 注意:默认不需要配置,自定义主题的时候可以用得到。