使用docsify 写开源文档

官网:https://docsify.js.org/#/

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行。

这将非常实用,如果只是需要快速的搭建一个小型的文档网站,或者不想因为生成的一堆 .html 文件“污染” commit 记录,只需要创建一个 index.html 就可以开始写文档而且直接部署在 GitHub Pages

一、初始化项目

1.1 安装Node.js

1.2 安装docsify-cli工具

命令行执行:

npm i docsify-cli -g

会在这个路径下

​ C:\Users\Administrator\AppData\Roaming\npm\node_modules

生成 docsify-cli 文件夹

1.3 初始化文档结构

先创建一个本地文件夹docs,然后执行命令

docsify init ./docs

会生成如下目录:

 -| docs/
-| .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
-| index.html 入口文件
-| README.md 会做为主页内容渲染

直接编辑 docs/README.md 就能更新网站内容

遇到的问题:

  1. 初始化docsify文档不成功

    升级node.js之后就成功了

1.4 本地实时预览

docsify serve docs

默认访问 http://localhost:3000

  • README文件:
# Headline
> An awesome project.
  • 预览效果:

二、定制导航栏

2.1 定制导航栏

<script>
window.$docsify = {
name: 'PassJava-Learning',
repo: 'https://github.com/Jackson0714/PassJava-Platform',
loadNavbar: true,
loadSidebar: true, // 加载自定义侧边栏
maxLevel: 2, // 默认情况下会抓取文档中所有标题渲染成目录,可配置最大支持渲染的标题层级。
subMaxLevel: 4, // 生成目录的最大层级
mergeNavbar: true, // 小屏设备下合并导航栏到侧边栏
alias: { // 定义路由别名,可以更自由的定义路由规则。 支持正则
'/.*/_sidebar.md': '/_sidebar.md',//防止意外回退
'/.*/_navbar.md': '/_navbar.md'
}
}
</script>
  • 添加_sidebar.md文件来配置侧边栏
* 介绍
* [PassJava 功能介绍](introduction/PassJava_introduction_01.md)
* [PassJava 必备知识](introduction/PassJava_introduction_02.md)
* PassJava 架构篇 * SpringBoot 学习篇
* [SpringBoot整合JDBC](springboot-tech/spring-boot-05-data-jdbc.md)
* [SpringBoot整合Druid](springboot-tech/spring-boot-06-data-druid.md)
* [SpringBoot整合MyBatis](springboot-tech/spring-boot-07-data-mybatis.md) * 工具篇
* [图床神器配置](tools/图床神器配置.md)
* [使用docsify写开源文档](tools/使用docsify写开源文档.md)
* [我的常用工具](tools/我的常用工具.md) * 想法
* [打造一款刷Java知识的小程序2](idea/打造一款刷Java知识的小程序2.md)
  • 添加_navbar.md文件来配置顶部导航栏
* 演示
* [后台管理]()
* [小程序端]() * 项目地址
* [后台平台](https://github.com/Jackson0714/PassJava-Platform)
* [后台管理](https://github.com/Jackson0714/PassJava-Portal)
* [学习教程](https://github.com/Jackson0714/PassJava-Learning)
  • 查看导航栏效果

三、定制封面页

  • 在index.html中添加封面页的配置
<script>
window.$docsify = {
coverpage: true
}
</script>
  • 添加_coverpage.md文件来配置封面页
![logo](images/logo.png)

# PassJava-Learning

> PassJava 学习教程,架构、业务、技术要点全方位解析。

PassJava 是一款帮助Java面试的开源系统,
可以用零碎时间利用小程序查看常见面试题,夯实Java基础。
采用流行的技术,如 SpringBoot、MyBatis、Redis、 MySql、
MongoDB、 RabbitMQ、Elasticsearch,采用Docker容器化部署。 [GitHub](https://github.com/jackson0714/PassJava-Learning)
[Get Started](README.md)
  • 查看封面效果

四、添加全文搜索

在index.html中添加全文搜索的配置

<script>
window.$docsify = {
search: {
placeholder: '搜索',
noData: '找不到结果!',
depth: 3
},
}
</script>

五、添加代码高亮

在index.html中添加代码高亮的配置

  <script src="//unpkg.com/prismjs/components/prism-bash.js"></script>
<script src="//unpkg.com/prismjs/components/prism-java.js"></script>
<script src="//unpkg.com/prismjs/components/prism-sql.js"></script>

六、添加一键拷贝代码

在index.html中添加一键拷贝代码的配置

<script src="//unpkg.com/docsify-copy-code"></script>

七、在Github上部署文档

八、部署到云服务器

1.添加nginx配置文件

  • 执行命令
sudo vim /etc/nginx/conf.d/pass_java_learning.conf
  • 更新配置信息
server {
listen 80;
server_name tech.jayh.club; location / {
root /home/ubuntu/jay/passjava/passjava-learning/PassJava-Learning/docs;
index index.html;
}
}

2.域名解析

主机记录:tech

记录类型:A

线路类型:默认

记录值:主机IP地址

3.访问 tech.jay.club

4. 遇到的问题

  • 404 未找到页面

    可以通过命令查看错误日志

    cat /var/log/nginx/error.log

    原因:docs 路径配置错误,下面三种路径都报404

    ​ /home/jay/passjava/passjava-learning/PassJava-Learning/docs;

    ​ /jay/passjava/passjava-learning/PassJava-Learning/docs;

    ​ ~/jay/passjava/passjava-learning/PassJava-Learning/docs;

    解决方案:

    改成 /home/ubuntu/jay/passjava/passjava-learning/PassJava-Learning/docs

  • 403 限制访问

    修改nginx.conf文件

    sudo vim nginx.conf

    user www-data 改为 user root

    重启 nginx 服务

    sudo service nginx restart

公众号

使用docsify 写开源文档的更多相关文章

  1. 使用开源文档工具docsify,用写博客的姿势写文档

    前提 下面的简介摘抄自docsify的官网 https://docsify.js.org 中的简介 docsify是一个神奇的文档网站生成器.他可以快速帮你生成文档网站.不同于GitBook.Hexo ...

  2. 这些.NET开源项目你知道吗?.NET平台开源文档与报表处理组件集合(三)

    在前2篇文章这些.NET开源项目你知道吗?让.NET开源来得更加猛烈些吧 和这些.NET开源项目你知道吗?让.NET开源来得更加猛烈些吧!(第二辑)中,大伙热情高涨.再次拿出自己的私货,在.NET平台 ...

  3. 拯救你的文档 – 【DevOps敏捷开发动手实验】开源文档发布

    今天上海的天气真是不错,风和日丽.再次来到微软上海紫竹研发中心,心情很是愉快,喜欢这里的大草坪,喜欢这里的工程气氛,更喜欢今天来陪我的小伙伴们. 这次动手实验培训与以往最大的不同就是采用了开源文档的方 ...

  4. .NET平台开源文档与报表处理组件包括Execel PDF Word等

    在前2篇文章这些.NET开源项目你知道吗?让.NET开源来得更加猛烈些吧 和这些.NET开源项目你知道吗?让.NET开源来得更加猛烈些吧!(第二辑)中,大伙热情高涨.再次拿出自己的私货,在.NET平台 ...

  5. 你会用AngularJS,但你会写AngularJS文档么?

    你会用AngularJS,但你会写AngularJS文档么? 涉及知识:gulp javascript 我们经常在写代码的时候要求写好注释,方便日后维护.但其实注释还有一个重要的用途:生成API文档. ...

  6. 《Spring Boot 实战纪实》之如何攥写需求文档

    目录 前言 (思维篇)人人都是产品经理 1.需求文档 1.1 需求管理 1.2 如何攥写需求文档 1.3 需求关键点文档 2 原型设计 2.1 缺失的逻辑 2.2 让想法跃然纸上 3 开发设计文档 3 ...

  7. 开源文档管理系统LogicalDOC测试报告---安装篇

    开源文档管理系统LogicalDOC测试报告---安装篇 分类: Linux2011-06-22 15:40 7436人阅读 评论(3) 收藏 举报 文档管理测试mysql数据库installerja ...

  8. 【DevOps敏捷开发动手实验】开源文档 v2015.2 stable 版发布

    Team Foundation Server 2015 Update 2版本终于在2周前的//Build 2016大会上正式发布了,借这个东风,小编也完成了[DevOps敏捷开发动手实验]开源文档的第 ...

  9. 看云&gitbook 写帮助文档 | 专注于文档在线创作、协作和托管

    看云 写帮助文档 | 专注于文档在线创作.协作和托管 https://www.kancloud.cn/manual/thinkphp/1678 https://www.gitbook.com/

随机推荐

  1. 从头认识js-js中的对象

    什么是对象? ECMA-262中把对象定义为:“无序属性的集合,其属性可以包含基本值,对象或者函数”.严格来讲,对象是一组没有特定顺序的值.对象的每个属性或方法·都有一个名字,而每个名字都映射到一个值 ...

  2. MVC09

    1.委托(delegate)调用静态方法 委托类似于C++中的函数指针. 某方法仅仅在执行的时候才能确定是否被调用. 是实现事件和回调函数的基础. 面向对象,安全性高. using System; u ...

  3. Yuchuan_Linux_C 编程之十一 进程间通信

    一.整体大纲 二.进程间通信概念及方法  Linux环境下,进程地址空间相互独立,每个进程各自有不同的用户地址空间.任何一个进程的全局变量在另一个进程中都看不到,所以进程和进程之间不能相互访问,要交换 ...

  4. .Net Core项目中整合Serilog

    前言:Serilog是.NET应用程序的诊断日志记录库.它易于设置,具有简洁的API,并且可以在所有最新的.NET平台上运行.尽管即使在最简单的应用程序中它也很有用,但当对复杂的,分布式的和异步的应用 ...

  5. 看过无数Java GC文章,这5个问题你也未必知道!

    看过无数Java GC文章,这6个问题你也未必知道! 读者朋友们可能已经看过太多关于Java垃圾回收相关的文章,如果没有,墙裂安利大家看下面这篇: 看完这篇垃圾回收,和面试官扯皮没问题了 本文不再重复 ...

  6. c++第一周测验

    本次得分为:14.00/14.00, 本次测试的提交时间为:2020-03-08, 如果你认为本次测试成绩不理想,你可以选择再做一次. 1 单选(1分) 下面程序片段哪个没错? 得分/总分 A. in ...

  7. drf呼啦圈

    呼啦圈 1.1 表结构设计 不会经常变化的值放在内存:choices形式,避免跨表性能低. 分表:如果表中列太多/大量内容可以选择水平分表 表自关联 from django.db import mod ...

  8. 一键配置openstack-cata版的在线yum源

    下面脚本可以直接复制来配置openstack-ocata版的yum源: echo "nameserver 8.8.8.8 nameserver 119.29.29.29 nameserver ...

  9. mongo密码的设置

    MongoDB 版本 v4.0.7 系统 Win10 注意: 要为数据库创建用户,必须先切换到相应的数据库: 要为数据库创建用户,必须先切换到相应的数据库: 要为数据库创建用户,必须先切换到相应的数据 ...

  10. 使用Python批量获取学生期末考试成绩

    以下是我们学校对于期末考试成绩临时查询的一个网站 我突发奇想,可不可以通过爬虫的方式批量获取成绩信息 于是说干就干 首先观察网页的请求 通过查看,我们可以很明显看到网站查询是通过对https://wx ...