https://github.com/chenbimo/yidocs
易文档
https://github.com/chenbimo/yidocs
Last synced: 19 days ago
JSON representation
易文档
- Host: GitHub
- URL: https://github.com/chenbimo/yidocs
- Owner: chenbimo
- License: apache-2.0
- Created: 2025-02-09T20:02:50.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-05-31T16:25:42.000Z (about 1 year ago)
- Last Synced: 2025-06-01T04:52:34.371Z (about 1 year ago)
- Language: JavaScript
- Size: 431 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
README
# yidocs 是什么？
中文名称 `易文档`，基于`vitepress`进一步封装而来。
旨在提供更加简单，易用，好用的文档体验。
### 仓库地址
[github - https://github.com/chenbimo/yidocs](https://github.com/chenbimo/yidocs)
### 效果演示
笔者的个人文章就是基于`yidocs`搭建的，点击查看即可。
[前端之虎陈随易 https://chensuiyi.me](https://chensuiyi.me)
### 功能特点
- ✅ 无需手动配置，自动生成导航栏。
- ✅ 无需手动配置，自动生成侧边栏。
- ✅ 良好的文档组织，顺序确定，无错乱。
### 为什么使用 yidocs
`yidocs` 开箱即用，并且无需手动配置 `侧边栏` 和 `导航栏`。
如果我们使用 `vitepress`，需要的配置如下：
```javascript
export default {
themeConfig: {
sidebar: {
'/guide/': [
{
text: 'Guide',
items: [
{ text: 'Index', link: '/guide/' },
{ text: 'One', link: '/guide/one' },
{ text: 'Two', link: '/guide/two' }
]
}
],
'/config/': [
{
text: 'Config',
items: [
{ text: 'Index', link: '/config/' },
{ text: 'Three', link: '/config/three' },
{ text: 'Four', link: '/config/four' }
]
}
]
}
}
};
```
使用 `yidocs`，配置如下即可：
```javascript
import { docsAuto } from '@yidocs/auto';
let { sideBar, navBar } = docsAuto();
export default {
themeConfig: {
sidebar: sideBar,
nav: navBar
}
};
```
最苦、最累、最麻烦的问题，交给笔者。
最好、最强、最方便的功能，留给你们。
### 下载使用
**下载 yidocs 接口开发模板**
如果你使用的是 `npm`：
```bash
npx dloo -n yidocs
```
如果你使用的是 `pnpm`：
```bash
pnpm dlx dloo -n yidocs
```
下载流程如下图。
```bash
D:\codes\chensuiyi\dloo>pnpm dlx dloo.js -n yidocs
ℹ 开发者：陈随易（https://chensuiyi.me）
-----------------------------------------
ℹ yidocs 接口项目开发模板下载中...
✔ 资源已下载到默认的 .dloo 目录，请移动到正确的目录!
```
将`.dloo` 目录中的`yidocs`模板全部复制到当前目录下，执行`pnpm install`安装命令，然后执行`pnpm run dev`命令查看效果。
## 设计理念
当然，要想如此方便地使用 `yidocs`，一些必要的约定还是要遵守的。
```bash
├───📁 markdown/
│ ├───📁 1-开源/
│ │ ├───📁 1-yite-cli/
│ │ │ ├───📁 1-基本简介/
│ │ │ │ ├───📄 1-基本介绍.md
│ │ │ │ ├───📄 2-快速体验.md
│ │ │ │ ├───📄 3-项目结构.md
│ │ │ │ └───📄 4-视频入门.md
```
**命名约定**
所有文件和目录，都要以 `数字-` 开头
如上所示，任何目录和文章，均以 `数字` + `短横线` 开头，作用就是用于 `文章` 和 `目录` 的排序。
如果没有人为的 `数字标识`，文档的目录和排序有可能是乱套的，所以此为 `yidocs` 的必要要求之一。
**层级约定**
一共有`2-3-4`三种结构层级。
```bash
├───📁 markdown
│ ├───📁 1-一级结构
│ │ └───📄 1-文章.md
│ ├───📁 2-二级结构
│ │ ├───📁 1-目录
│ │ │ └───📄 1-文章.md
│ ├───📁 2-三级结构
│ │ ├───📁 1-目录
│ │ │ ├───📁 1-目录
│ │ │ │ └───📄 1-文章.md
```
一级结构在顶部导航没有`箭头`，点击即会展示该文章内容，适合`目录-文章`的模式，比如`关于我`。
二级结构类似`下拉列表`，需要选择其`二级菜单`才会显示对应的文章内容，适合`分类-目录-文章`的模式，比如说明书。
三级结构会把目录下的所有目录展示在侧边栏，适合`分类-项目-目录-文章`的模式，比如复杂的开源手册。
这就是 `yidocs` 的文件组织结构。
不满足此规则的文件，在编译的控制台将会进行提示，且对应文件将不会在文档中显示。
建议不想显示的目录或文章，使用`下划线+名称`的模式命名，这样所有的隐藏目录或文件都会在目录的顶部展示，比如`_这是隐藏文件.md`。
### 插件扩展
`yidocs` 提供了实用的插件，可以一键安装使用。
#### 会员内容隐藏插件 - @yicocs/vip
**安装：**
```bash
pnpm add @yidocs/vip
```
**配置：**
```js
import markdownItVip from '@yidocs/vip';
export default {
markdown: {
theme: 'one-dark-pro',
lineNumbers: true,
config: (md) => {
md.use(markdownItVip);
}
}
};
```
**使用：**
格式如下：
开头：``。
结尾：``。
```markdown
这是会员隐藏内容
```
### 版权说明
`yidocs(易文档)` 使用 `Apache 2.0` 协议开源
> 一句话总结：开源不等于放弃版权，不可侵犯原作者版权，改动处要做说明，可以闭源使用。
拥有版权（Copyright）意味着你对你开发的软件及其源代码拥有著作权，所有权和其他法定权利，使用一个开源协议并不意味着放弃版权。
在 `Apache 2.0` 协议许可下，您可以：
- **商业化使用**（这意味着，您可以出于商业目的使用这些源代码）
- **再分发**（这意味着，您可以将源代码副本传输给其他任何人）
- **修改**（这意味着，您可以修改源代码）
- **专利使用**（这意味着，版权人明确声明授予您专利使用权）
- **私人使用**（这意味着，您可以出于一切目的私下使用和修改源代码）
唯须遵守以下条款：
- **协议和版权通知**（这意味着，软件中必须包含许可证和版权声明的副本）
- **状态更改说明**（如果您更改软件，您应当提供适当的说明）
除此之外，该软件：
- **提供责任限制**（版权人声明不对使用者造成的任何损失负责）
- **限制商标使用** (不能使用版权人的商标)
- **不提供任何担保**（版权人声明不为该软件的品质提供任何担保）
进一步说明：
1. 本软件又叫本 **作品**，可以是源码，也可以是编译或转换后的其他形式。**衍生作品** 是在本作品的基础上修改后的有原创性的工作成果。本作品的 **贡献者** 包括许可人和其他提交了贡献的人，以下统称 **我**。
2. 我授予你权利：你可以免费复制、使用、修改、再许可、分发本作品及衍生作品（可以不用公开源码）。
3. 如果本软件涉及我的专利（或潜在专利），我在此授予你专利许可，你可以永久性地免费使用此专利，用于制作、使用、出售、转让本作品。如果你哪天居然告本作品侵权，你的专利许可在你告我那天被收回。
4. 你在复制和分发本作品或衍生作品时，要满足以下条件。
- 带一份本许可证。
- 如果你修改了什么，要在改动的文件中有明显的修改声明。
- 如果你以源码形式分发，你必须保留本作品的版权、专利、商标和归属声明。
- 如果本作品带了 **NOTICE** 文件，你就得带上 **NOTICE** 文件中包含的归属声明。即便你的发布是不带源码的，你也得带上此文件，并在作品某处予以展示。
- 你可以对自己的修改添加版权说明。对于你的修改或者整个衍生作品，你可以使用不同的许可，但你对本作品的使用、复制和分发等，必须符合本许可证规定。
5. 你提交贡献就表明你默认遵守本许可的条款和条件。当然，你可以和我签订另外的专门的条款。
6. 你不许使用我的商品名、商标、服务标志或产品名。
7. 本作品是 **按原样**（AS IS）提供的，没有任何保证啊，你懂的。
8. 我可不负任何责任。除非我书面同意，或者法律有这样的要求（例如对故意和重大过失行为负责）。
9. 你可以向别人提供保证，你可以向别人收费，但那都是你的事，别给我惹麻烦。
注意以上的 **我**，既包含了许可人，也包含了每位 **贡献者**。