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