如何写文档

当前文档使用的是 @sugarat/theme 主题搭建的，基础功能已全部处理完毕，包括对应的目录，如果有新的需求，可以告知我添加，只需要在对应的目录下添加对应的 markdown 文件即可。

如果需要用到图片资源，在public目录下添加对应的目录，例如文档路径frontend/study/basics.md，public目录中新建对应的目录frontend/study/basics，在basics目录中添加对应的图片即可，在basics.md文件中引入地址/frontend/study/basics/图片.png|jpg，一定要以/开头，否则引入的是相对路径，在build模式下会找不到。

主题配置

这里将配置分成了2块，首页已配置好，可以不用动，主要是 Article 配置

• home：首页的独立配置
• Article：单篇文章独立配置

TIP

主题继承默认主题配置，即原主题配置依然生效

官方内置的👉🏻 markdown 能力 👈🏻

主题相关的 frontmatter 汇总

const frontmatter = [
  'layout',
  'blog',
  'title',
  'description',
  'descriptionHTML',
  'cover',
  'hiddenCover',
  'hidden',
  'author',
  'readingTime',
  'comment',
  'date',
  'tag',
  'tags',
  'categories',
  'sticky',
  'top',
  'recommend',
  'publish',
  'buttonAfterArticle',
]

对照表

属性	描述
layout	布局
blog	博客首页
title	标题
description	描述
descriptionHTML	描述HTML
cover	封面
hiddenCover	隐藏封面
hidden	隐藏首页展示
author	作者
readingTime	阅读时间
comment	评论
date	日期
tag	标签
tags	同标签
categories	同标签
sticky	精选置顶
top	首页置顶
recommend	推荐列表控制
publish	是否发布
buttonAfterArticle	文章底部引导操作按钮

Article 配置

通用的常规配置概览说明

---
author: 【重要】作者名，请写自己的名字
---

<!-- 下边几个一般情况下都不需要添加 -->

title: 有特殊需求了配置，一般不需要，默认取的是一级标题
description: 默认取内容前100字，如果内容不合适的，可以手动配置
descriptionHTML: 自定义HTML内容，会覆盖 description，有特殊需要了配置
cover: 未指定时，默认取文章中出现的第一张图片，或者自定义
hidden: 是否隐藏首页展示，默认展示，一般不用

<!-- 下边几个视情况添加 -->

sticky: 精选置顶，一般不用，优质内容需要置顶，值越大展示越靠前
top: 用于设置在首页置顶展示的文章，从 1 开始，值越小越靠前
recommend: 推荐列表控制，默认展示，一般不用
sort: 文章排序，从小到大，值越小越靠前，特殊情况下使用

---

每个字段的详细描述见下方说明

title

用于设置文章在首页卡片列表里展示的标题

例如changelog.md有如下内容

---
title: 更新日志
---

# Changelog

在首页就会有如下展示

不设置情况下默认取一级标题# 一级标题

description

用于设置文章在首页卡片列表里展示的描述信息

例如about.md有如下内容

---
description: 简单介绍主题的由来和实现原理
---

# 关于主题

基于 [vitepress](https://vitepress.dev/) 的自定义主题实现

在首页就会有如下展示

不设置的情况下，默认取文章内容的前100个字符

descriptionHTML

使用自定义的HTML内容设置文章在首页卡片列表里展示的描述信息

---
descriptionHTML: '
<span style="color:var(--description-font-color);">1分钟内完成自己的博客创建</span>
<pre style="background-color: #292b30; padding: 15px; border-radius: 10px;" class="shiki material-theme-palenight"><code>
    <span class="line"><span style="color:#FFCB6B;">npm</span><span style="color:#A6ACCD;"> </span><span style="color:#C3E88D;">create</span><span style="color:#A6ACCD;"> </span><span style="color:#C3E88D;">@sugarat/theme@latest</span></span>
</code>
</pre>'
---

cover

• Type: string|false

用于设置文章在首页卡片列表里展示的 封面信息

① 设置封面

---
cover: https://img.cdn.sugarat.top/mdImg/MTY3MzE0Njg5NDY4OQ==673146894689
---

② 不展示封面

---
cover: false
---

未指定时，默认取文章中出现的第一张图片

同时如果手动设置了，封面将同时在文章页展示

可以通过下面的 hiddenCover 隐藏文章页的展示

hiddenCover

hiddenCover 控制是否展示当前文章的封面，全局配置开关见 article.hiddenCover

---
hiddenCover: true
cover: url
---

如果hiddenCover为 true 则不会在文章页展示上述的封面

hidden

用于设置文章是否出现在首页的列表里

---
hidden: true
---

比如设置在changelog.md里，首页将不会展示此项

author

用于单独设置文章的作者信息

---
author: 粥里有勺糖
---

在首页的展示样式

在文章顶部展示的样式

如果没有单独设置则会默认使用全局的 author 配置，这个在 全局配置: author 有介绍

readingTime

单独设置是否展示文章的预计阅读时间，全局配置开关见 article.readingTime

---
readingTime: true
---

comment

单独为某篇文章设置是否开启评论

---
# 关闭评论
comment: false
---

date

• type：string | false

单独设置文章的发布时间，不设置的情况下默认会通过Git取文件最后修改时间，设置为 false 则不会在文章页展示

---
date: 2023-01-04
---

---
date: 2023-01-08 20:00:00
---

展示规则，实现代码见：packages/theme/src/utils/index.ts

• 小于1分钟：xx秒前
• 小于1小时：xx分钟前
• 小于1天：xx小时前
• 小于1周：xx天前
• 其它：按照实际时间展示 yyyy-MM-dd

---
date: false
---

tag

用于按标签给文章分类，同时，在文章页标签可点击跳转

---
tag:
  - 日志
tags:
  - 信息
categories:
  - 测试分类
---

tags

效果同上

categories

效果同上

sticky

用于设置在首页展示的 精选文章，值越大展示越靠前

---
sticky: 1
---

top

• type: number

用于设置在首页置顶展示的文章，从 1 开始，值越小越靠前

---
top: 1
---

recommend

• type: number | false | string | string[] | [...string[], number]

可用于配置左侧推荐列表数据表现，默认只展示同级目录下的文章

• 文章左侧展示的 推荐文章 顺序（越小越靠前）
• 在推荐列表中隐藏掉不展示
• 手动关联不同目录的文章进行展现

① 只调整顺序

---
recommend: 1
---

② 在列表中隐藏

---
recommend: false
---

③ 关联不同目录的文章

---
# 直接设置文章的关键词
recommend: 'Node.js'
# 设置多个关键词
recommend: ['Node.js', 'css', 'html']
# 设置关键词并设置顺序
recommend: ['Node.js', 'css', 'html', 1]
---

手动设置顺序	隐藏	自定义关联

sort

• type: number

文件夹中的文件默认排序方式是通过recommend从小到大排序，因特殊需求（比如：需要写文章合集）需要自定义左侧菜单效果，此时recommend需要设置为false，否则加上自定义左侧菜单会出现两个，导致效果不好，为了保持良好的阅读顺序，可以通过 sort 辅助排序

目录效果	菜单效果	菜单源码

publish

• type: false

表明文章是否发布，用于设置文章是否出现在首页和侧边栏里

---
publish: false
---

等价于

---
hidden: true
recommend: false
---

比如设置在changelog.md里，首页将不会展示此项

同时，左侧边栏也不会展示