Docute超简单的文档工具
1、前言
在我们日常的开发和学习中,我们可能会进行在线文档的写作,为了能够让我们的文档公开给大家查阅,我们可能需要将其发布到公网。这个时候,我们会有很多的文档软件选项,比如GitBook、Docsify、MdBook、Docusaurus2、MkDocs等等。
今天我们就来介绍一款和Docsify高度相似的文档框架,它就是Docute。相比Docsify,Docute功能简单,算是一个小清新的文档软件,和Docsify一样,Docute也是运行时渲染,不利于SEO,仅适合作为项目文档、教程文档来使用。
2、快速开始
2.1、项目初始化
Docute最新版本已经来到了V4,相比V3更加简约和简单。而且其支持使用在线CDN资源和Node离线包两种方式,今天我们采用CDN资源的方式进行演示,当然你也可以安装NodeJs后使用npm安装Docute的包进行离线的文档开发构建。
第一步: 创建项目文件夹docute-demo
第二步: 创建index.html并向其中输入以下内容:
<!DOCTYPE html>
<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>My Docs</title><link rel="stylesheet" href="https://unpkg.com/docute@4/dist/docute.css"></head><body><div id="docute"></div><script src="https://unpkg.com/docute@4/dist/docute.js"></script><script>new Docute({ title: 'Docute Demo',// 代码高亮配置 highlight: [ 'typescript', 'go', 'python'],// 主题切换开关 darkThemeToggler: true,// 顶部banner配置 banner: `Please <a href="https://donate.com/link"> donate</a> <ExternalLinkIcon /> to support this project!`,// 顶部导航栏配置 nav: [// A dropdown menu{ title: '语言', children: [{ title: '2', link: '/'},{ title: '1', link: '/'}]},{ title: 'Home', link: '/'},{ title: 'MyBlog', link: 'https://www.u1s1.vip'}],// 侧边栏配置 sidebar: [// A sidebar item, with child links{ title: '教程', children: [{ title: '快速开始', link: '/a/start'},{ title: '安装', link: '/install'}]},// An external link{ title: 'GitHub', link: 'https://github.com/egoist/docute'}]})</script></body>
</html>
如上,Docute的主页就是index.html,项目的配置都在script标签中进行。
第三步: 创建首页README.md文件并向其中输入以下内容:
## 首页
欢迎来到Docute的世界。
> 这是引用
---
1. 有序1
2. 有序2
2.2、启动预览
在完成以上步骤后,我们就可以使用Python的http.server或者Caddy或者Nginx等服务器将Docute项目托管,然后在浏览器进行预览。
这里我们使用dufs启动。
cd docute-demo
dufs --render-index
然后打开:http://127.0.0.1:5000/
查看效果:
可以看到效果已经出来。
目前的最新版本存在一个BUG,就是下拉菜单的位置有错位。等待后续修复。
2.3、顶部导航栏配置
在Docute中,顶部导航栏配置是nav
配置块。我们可以在nav
中添加顶部菜单,下拉菜单等。
nav: [// 下拉菜单{title: '语言',children: [{title: '2',link: '/'},{title: '1',link: '/'}]},// 独立菜单{title: 'Home',link: '/'},{title: 'MyBlog',link: 'https://www.u1s1.vip'}
],
2.4、侧边栏配置
在Docute中,顶部导航栏配置是sidebar
配置块。我们可以在sidebar
中添加侧边导航目录,独立菜单,下拉菜单等。
sidebar: [// 侧边导航{title: '教程',children: [{title: '快速开始', // 标题link: '/a/start' // 标题对应的markdown文件},{title: '安装',link: '/install'}]},// 外部链接{title: 'GitHub',link: 'https://github.com/egoist/docute'}
]
2.5、其他配置
我们还可以在index.html的script中对Docute的代码高亮、主题切换等进行配置。
// 站点标题
title: 'Docute Demo',
// 代码高亮
highlight: [
'typescript',
'go',
'python'
],
// 主题切换开关
darkThemeToggler: true,
// 顶部banner,主要用于广告和提示
banner: `Please <a href="https://donate.com/link">
donate</a> <ExternalLinkIcon /> to support this project!`,
更多的配置
// 站点logo
logo: '',
// 站点在线编辑的github项目路径
editLinkBase: 'https://github.com/USER/REPO/blob/master/docs',
// 编辑文档的提示语
editLinkText: '编辑我',
// Docute主题根据系统主题来,windows10+,macOS (Mojave)+
detectSystemDarkTheme: true,
// 站点布局风格,全屏、居中、居左可选
layout: 'narrow ',
// 站点底部信息
footer: 'xxx',
// 开启图片缩放
imageZoom: true
2.6、创建示例文档
前面我们已经在sidebar中配置了快速开始和安装两个导航菜单。其中快速开始的路由是/a/start
即在index.html所在路径下需要创建a/start.md
文件;安装的路由是install
,即需要在index.html的路径下创建名为install.md
的文件。
index.html所在路径为项目根路径。
我们创建a/start.md
文件并输入以下内容:
## start
```python
print("hello")
我们创建`install.md`文件并输入以下内容:
install
这是安装文档。
这是引用
安装 1
xx
安装 2
xxx
安装完成
xxx
启动预览,查看侧边导航栏效果:<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9387806ff3434a6885978829fd275faf~tplv-k3u1fbpfcp-zoom-in-crop-mark:4536:0:0:0.image" style="margin: auto" />如上,Docute和大多数的文档系统一样,是将`##`作为标题1来渲染的。### 2.7、一些特殊样式**提示块**
普通提示 警告提示 危险提示 ```
徽章
主要用于为一些特殊字符进行特殊标记。
- 样式1 <Badge type="tip">Tip</Badge>
- 样式2 <Badge type="success">Success</Badge>
- 样式3 <Badge type="warning">Warning</Badge>
- 样式4 <Badge type="danger">Danger</Badge>
- 样式5 <Badge color="magenta">Custom Color</Badge>
3、最后
“danger”>Danger
- 样式5 Custom Color
<img src="https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/0cb7d1a23c054811a5ee783dc06da613~tplv-k3u1fbpfcp-zoom-in-crop-mark:4536:0:0:0.image" style="margin: auto" />3、最后
----目前Docute依然定位轻量,简单的文档系统。对于搜索评论等功能目前支持的不好。但是正是因为功能简单,专注文档吸引了一部分忠实用户。如果你也想要做一个纯粹的文档平台,那么Docute将会帮上你的忙。
Docute超简单的文档工具相关推荐
- JBoot 全网上最好用的 API 文档工具
简介 到目前为止,Jboot 已经开源超过了 5 年的时间,迭代了 200+ 个版本,已经被超过 1000+ 公司在使用,其中包含了多个知名的上市公司,我们了解到的多个使用 Jboot 开发的产 ...
- Eolink 征文活动- -后端研发需要的API文档工具
Eolink功能太多,一两篇文章聊不完,这篇文章只是聊聊Eolink的API文档管理功能. 首先大致说说我所认知的API文档工具历史. 我所知的API文档工具历史 我是2010年左右参 ...
- 干掉 Swagger + Postman?测试接口直接生成API文档,这个国产文档工具真香!
点击上方"芋道源码",选择"设为星标" 管她前浪,还是后浪? 能浪的浪,才是好浪! 每天 10:33 更新文章,每天掉亿点点头发... 源码精品专栏 原创 | ...
- 干掉 Postman?测试接口直接生成API文档,这个文档工具真香!
欢迎关注方志朋的博客,回复"666"获面试宝典 实不相瞒我的收藏夹里躺着很多优质的开源项目,我有个爱好平时遇到感兴趣的开源项目都会记录下来,然后有时间在慢慢研究.前几天刚给同事分享 ...
- 生成chm文档工具- Sandcastle -摘自网络
Sandcastle是微软官方的文档生成工具,NDoc开发停止后,这个貌似也是唯一的一个这方面的工具.它从dll文件及其xml注释文件能够 生成完整的帮助文档,支持多种生成格式(Helpe1x:chm ...
- 团队合作开发的两种文档工具
前言 团队中,需要从需求分析开始确定,一直到项目的开发完成,中间要经历各种事情,需要各种任务来维持,一直到合作开发完成,所以需要一个团队协作查看的任务工具.那么这里推荐的有两种,trello,和tea ...
- API文档工具knife4j使用详解
api文档 编写api文档是一个费时的操作,过程枯燥.那有没有一种可以自动生成api文档的工具呢,答案是有,比如swagger就是可以自动生成的,像yapi.apidoc.showdoc等等是需要我们 ...
- Swagger 文档中文版,国产API 文档工具使用教程
swagger文档.swagger ui 在后端开发中使用非常广泛,接口文档开发和代码生成等功能非常好用. 但swagger是付费的产品,而免费版的swagger 文档需要自己去配置,流程非常复杂,因 ...
- Popular MVC框架swagger+knif4j接口文档工具使用示例
Popular MVC框架swagger接口文档工具使用示例 简介 此项目介绍如何使用popularmvc内置的swagger+knife4j实现简单易用的实时API文档,支持在线调试接口! 此项目只 ...
最新文章
- docker desktop使用入门
- 设计输出实数的格式,实数用%6.2f格式输出
- validating和validated的区别
- 大咖茶话会 | 与原新浪微博副总裁零距离沟通
- RUNNING JUPYTER NOTEBOOKS ON A REMOTE SERVER VIA SSH
- SQL语句中timestamp进行排序BUG
- 三相pmsm矢量控制仿真模型_学术|基于新型滑模观测器的永磁同步电机无传感器矢量控制系统...
- 几行代码,网盘链接提头来见!
- 操作系统:第二章 进程管理2 - 处理机调度
- python3爬虫初探(四)之文件保存
- thinkPHP利用ajax异步上传图片并显示、删除
- activity-启动动画的设定(下面弹出出现,弹入下面消失)
- Elasticsearch--进阶-match_phrase短语匹配---全文检索引擎ElasticSearch工作笔记012
- 给程序员的建议(转自李开复)
- ActiveMQ开发配置与用例
- Visio图片导入到Word里面的步骤
- 【CAD】CAD插件
- 安卓linux开机画面,安卓开机画面_安卓开机动画修改_安卓开机动画修改器-Guide信息网...
- AEJoy —— 详解 AE 如何将 png 序列帧导出为 SVGA 动画文件
- 诺基亚Q4净利润5.64亿美元 同比增54%