premise
The following introduction is excerpted from the introduction in docsify's official website https://docsify.js.org
"Docsify" is a magical document website generator. He can quickly help you generate a document website. Is different GitBook, Hexothe place is that it does not generate static .htmldocuments, all the conversion work is done at run time. If you want to start using it, you only need to create one index.htmlto start writing documents and deploy them directly in GitHub Pages(Code Cloud Pages, Amoyun OSSor Goose Cloud, COSetc.). Its main features are as follows:
No need to build, publish directly after writing the document (
markdowndocument conversion at runtime )Easy to use and lightweight (~21kB after compression, of course
markdownthe size of the document is not included here )Intelligent full text search
plentiful
APISupport
Emoji, you can add emoticons to the textcompatible
IE11Support server-side rendering
SSR
The biggest advantage of "docsify" is that it allows users to feel "use the posture of blogging to write documents, and vice versa: use the posture of writing documents to write blogs" . docsifyThe cost of learning is very low, the deployment is simple, and the official documentation is very complete. In principle, only understandable markdowngrammar and Node.jsinstallation are required , and it is ITalso very friendly to non- technical practitioners. The site of the well-known technical public account owner "JavaGuide" is docsifyconstructed using the method. The following docsifypostures are briefly introduced .
Install docsify and initialize the project
docsifyIt is a Node.jsplug-in, so Node.js needs to be installed in advance. After the installation is complete, install it globally through the following command docsify:
npm i docsify-cli -g
Assuming that there is a /docsify-demodirectory in the disk, the docsify initproject can be initialized directly through the command in this directory :
# 先进入docsify-sample目录，在docsify-sample目录打开命令行
docsify init
After the command is executed successfully, three new files will be generated in the project directory as follows:
index.htmlFor the entry file,css,jsand configuration items are modified in this file.README.mdWill be rendered as the default homepage content..nojekyllUsed to preventGitHub Pagesignoring files beginning with underscores.
Then call the docsify servecommand and access http://localhost:3000to perform local preview, the effect is as follows:
❝When briefly introducing the functions of docsify, all the default configuration parameters are used. In general, it is not recommended to modify the default configuration items.
docsifyThe configuration item modification or the addition of static resources are basically index.htmloperated in the file, while other markdownfiles (including the built-in sidebar, cover file and articles added by yourself) are loaded and rendered at runtime.
basic configuration
A basic configuration item is as follows:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>神奇的docsify</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<!-- 设置浏览器图标 -->
<link rel="icon" href="/favicon.ico" type="image/x-icon" />
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
<!-- 默认主题 -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
<!-- 定义加载时候的动作 -->
<div id="app">加载中...</div>
<script>
window.$docsify = {
// 项目名称
name: 'docsify-demo',
// 仓库地址，点击右上角的Github章鱼猫头像会跳转到此地址
repo: 'https://github.com/zjcscut/docsify-demo',
// 侧边栏支持，默认加载的是项目根目录下的_sidebar.md文件
loadSidebar: true,
// 导航栏支持，默认加载的是项目根目录下的_navbar.md文件
loadNavbar: true,
// 封面支持，默认加载的是项目根目录下的_coverpage.md文件
coverpage: true,
// 最大支持渲染的标题层级
maxLevel: 4,
// 自定义侧边栏后默认不会再生成目录，设置生成目录的最大层级，建议配置为1或者2
subMaxLevel: 2
}
</script>
<script>
// 搜索配置
window.$docsify = {
search: {
maxAge: 86400000,
paths: auto,
placeholder: '搜索',
noData: '找不到结果',
depth: 4,
hideOtherSidebarContent: false,
namespace: 'docsify-demo',
}
}
</script>
<!-- docsify的js依赖 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<!-- emoji表情支持 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
<!-- 图片放大缩小支持 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
<!-- 搜索功能支持 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>
There are more configuration items you can refer docsifyto 定制化 - 配置项a section in the document. The more customized things, the more difficult it is to maintain. It is recommended to use the default file rendering for the sidebar, navigation bar and cover:
Sidebar and Navigation Bar
The "navigation bar" needs to be configured in the root directory index.htmlor in a _navbar.mdfile, and can be used emoji. Modify the index.htmlfile here such as:
<!-- index.html -->
<body>
<nav>
<a href="https://throwx.cn">???????? Throwable's Blog</a>
<a href="https://spring.throwx.cn">❤️❤️ Spring专栏</a>
</nav>
<div id="app">加载中......</div>
</body>
The effect is as follows:
The "sidebar" needs to be _sidebar.mdconfigured in the file in the root directory . The basic format is:
* 第一个章节的标题
* [第一个章节第1篇文章的标题](第一个章节第1篇文章的标题的markdown文件)
* [第一个章节第2篇文章的标题](第一个章节第2篇文章的标题的markdown文件)
......
* 第二个章节的标题
* [第二个章节第1篇文章的标题](第二个章节第1篇文章的标题的markdown文件)
* [第二个章节第2篇文章的标题](第二个章节第2篇文章的标题的markdown文件)
......
The rendered sidebar effect is:
第一个章节的标题
- 第一个章节第1篇文章的标题
- 第一个章节第2篇文章的标题
第二个章节的标题
- 第二个章节第1篇文章的标题
- 第二个章节第2篇文章的标题
Theme switching
❝To switch the theme, you only need to switch the corresponding theme css file in index.html in the root directory❞
docsifyAll supported themes and preview effects currently listed in the official list are as follows:
Vue(Default theme):<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
Buble：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">
Dark：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
Pure：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">
Dolphin：<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">
Docsify-Themeable-Default：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
Docsify-Themeable-Sample：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
Docsify-Themeable-Sample-Dark：<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
The one that suits you best.
Design cover
The cover page needs to be _coverpage.mdconfigured in the file in the root directory . For example docsify, the cover content of the official document is as follows:
<!-- _coverpage.md -->
# docsify <small>3.5</small>
> 一个神奇的文档网站生成器。
- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题
[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#docsify)
The rendering effect is as follows:
The author also made a ugly homepage with reference to this configuration, the content is as follows:
# Spring Album <small>0.0.1</small>
> 试下写个Spring相关的专栏，这是原始版本，暂定包括下面的栏目：
- `SpringBoot2.x`入门系列
- `SpringBoot2.x`进阶和实战
- `SpringBoot`源码系列
[GitHub](https://github.com/zjcscut/spring-boot-guide)
[Get Started](#Spring)
The rendering effect is as follows:
The content of the cover can be written in grammar htmlor in use markdown, with a high degree of freedom.
❝The background color of the cover is randomly switched, you can use a fixed background color ❞
docsi fy project deployment
Mainly introduce the deployment of GitHub PagesTencent Cloud COS, other similar Coding Pagesor Alibaba Cloud OSSdeployment methods, etc. can be deployed with reference to the two methods introduced below.
Deploy on GitHub Pages
First build a Githubwarehouse and push the project files up:
Click the Settingsbutton in the red circle in the upper right corner to configure Github Pages:
After saving, configure the custom domain name resolution, that is, resolve the domain name to the project Github Pages, and then you can access the project through the custom domain name.
❝Of course, Github also provides a free subdomain for each account: account.github.io, you need to build a warehouse named "account.github.io", push the project files to this warehouse, and configure Github Pages You can access this project through "account.github.io". ❞
Deployed in Tencent Cloud COS
I've put together a sub-domain name spring.throwx.cnresolves to Tencent cloud COSof the docsifyproject, the process is simple. First create an object storage bucket and set it to "public read private write" :
Then docsifycopy the files in the entire project to the bucket, "The index.htmlfiles must be in the root directory of the bucket" :
Then 基本配置 - 静态网站the index document (home page) in the configuration bucket is as follows:
After completing this step, you can COSaccess the docsifyproject through the public domain name . Finally COS, the intranet domain name resolved to the subdomain name can access the project through the customized subdomain name, and the effect is as follows:
❝New Tencent Cloud users have a six-month free trial privilege of COS, and it is recommended to try new things.❞
summary
If you like markdowngrammar and want to use the posture of blogging to write documents, or use the posture of writing documents to write blogs, you can try it docsify. You should like this excellent open source tool.
Reference materials:
docsifyOfficial documents:https://docsify.js.org
Sample project warehouse:
Github：https://github.com/zjcscut/docsify-demo
Entrance to online demo of sample project:
Tencent Cloud:
https://spring.throwx.cn
There is no way, but the technique can be achieved; if there is no way, it ends with the technique
Welcome everyone to follow the Java Way public account
Good article, I am reading ❤️