.net编写抽奖的文档_使用开源文档工具docsify，用写博客的姿势写文档
前提
?下面的簡介摘抄自docsify的官網(wǎng) https://docsify.js.org 中的簡介
?「docsify」是一個神奇的文檔網(wǎng)站生成器。他可以快速幫你生成文檔網(wǎng)站。不同于GitBook、Hexo的地方是它不會生成靜態(tài)的.html文件，所有轉換工作都是在運行時。如果你想要開始使用他，只需要創(chuàng)建一個index.html就可以開始編寫文檔并直接部署在GitHub Pages(碼云Pages、阿某云OSS或者鵝云COS等等)。它的主要特性如下：
- 無需構建，寫完文檔直接發(fā)布(運行時markdown文檔轉換)
- 容易使用并且輕量(壓縮后 ~21kB，當然這里不包括markdown文檔的大小)
- 智能的全文搜索
- 豐富的API
- 支持Emoji，可以在文中添加表情
- 兼容IE11
- 支持服務端渲染SSR
「docsify」的最大優(yōu)勢是可以讓使用者感受到「用寫博客的姿勢去編寫文檔，反過來說也行：用寫文檔的姿勢去寫博客」。docsify的學習成本很低，部署簡單，官方文檔十分完善，原則上只需要理解markdown的語法和Node.js的安裝即可，對于非IT技術從業(yè)者也十分友好。知名的技術公眾號號主「JavaGuide」的站點就是采用docsify構建的。下文簡單介紹docsify的使用姿勢。
安裝docsify和初始化項目
docsify是一個Node.js插件，所以需要提前安裝Node.js。安裝完畢后，通過下面命令全局安裝docsify：
npm?i?docsify-cli?-g假設磁盤中有一個/docsify-demo目錄，在該目錄下可以直接通過docsify init命令初始化項目：
#?先進入docsify-sample目錄，在docsify-sample目錄打開命令行docsify?init
命令執(zhí)行成功后，會在項目的目錄生成三個新的文件如下：
- index.html為入口文件，css、js以及配置項都在此文件中修改。
- README.md會作為默認主頁內(nèi)容渲染。
- .nojekyll用于阻止GitHub Pages忽略掉下劃線開頭的文件。
接著調(diào)用docsify serve命令然后訪問http://localhost:3000即可進行本地預覽，效果如下：
?下面在簡單介紹docsify的功能使用的時候，全部使用默認的配置參數(shù)，其實一般情況下，不太建議進行默認配置項的修改。
?docsify的配置項修改或者靜態(tài)資源增添基本都在index.html文件中操作，而其他markdown文件(包括內(nèi)建的側邊欄、封面文件和自己添加的文章)都是運行時加載和渲染的。
基本配置
一份基本的配置項如下：
html><html?lang="en">
<head>
????<meta?charset="UTF-8">
????<title>神奇的docsifytitle>
????<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>
????
????<script?src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js">script>
????
????<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>
還有更多配置項可以參考docsify文檔中的定制化 - 配置項一小節(jié)，定制的東西越多，維護的難度就越大。側邊欄、導航欄和封面都建議采用默認的文件渲染：
| 側邊欄 | /_sidebar.md |
| 導航欄 | /_navbar.md |
| 側邊欄 | /_coverpage.md |
側邊欄與導航欄
「導航欄」需要在根目錄的index.html或者_navbar.md文件中配置，可以使用emoji，這里修改index.html文件如：
<body>
??<nav>
????<a?href="https://throwx.cn">???Throwable's?Bloga>
????<a?href="https://spring.throwx.cn">?????Spring專欄a>
??nav>
??<div?id="app">加載中......div>
body>
效果如下：
「側邊欄」需要在根目錄的_sidebar.md文件中配置，基本的格式是：
*?第一個章節(jié)的標題?*?[第一個章節(jié)第1篇文章的標題](第一個章節(jié)第1篇文章的標題的markdown文件)
?*?[第一個章節(jié)第2篇文章的標題](第一個章節(jié)第2篇文章的標題的markdown文件)
?......
*?第二個章節(jié)的標題
?*?[第二個章節(jié)第1篇文章的標題](第二個章節(jié)第1篇文章的標題的markdown文件)
?*?[第二個章節(jié)第2篇文章的標題](第二個章節(jié)第2篇文章的標題的markdown文件)
?......
渲染后的側邊欄效果是：
第一個章節(jié)的標題???-?第一個章節(jié)第1篇文章的標題
???-?第一個章節(jié)第2篇文章的標題
第二個章節(jié)的標題
???-?第二個章節(jié)第1篇文章的標題
???-?第二個章節(jié)第2篇文章的標題
主題切換
?切換主題只需要在根目錄的index.html切換對應的主題css文件即可
?目前docsify官方中列出來的所有支持主題和預覽效果如下：
- Vue(默認主題)：
- Buble：
- Dark：
- Pure：
- Dolphin：
- Docsify-Themeable-Default：
- Docsify-Themeable-Sample：
- Docsify-Themeable-Sample-Dark：
最有一款合你心水。
設計封面
封面需要在根目錄的_coverpage.md文件中配置，例如docsify官方文檔的封面內(nèi)容如下：
#?docsify?
>?一個神奇的文檔網(wǎng)站生成器。
-?簡單、輕便?(壓縮后?~21kB)
-?無需生成?html?文件
-?眾多主題
[GitHub](https://github.com/docsifyjs/docsify/)
[Get?Started](#docsify)
渲染效果如下：
筆者也參照此配置做了一個丑丑的主頁，內(nèi)容如下：
#?Spring?Album?
>?試下寫個Spring相關的專欄，這是原始版本，暫定包括下面的欄目：
-?`SpringBoot2.x`入門系列?
-?`SpringBoot2.x`進階和實戰(zhàn)
-?`SpringBoot`源碼系列
[GitHub](https://github.com/zjcscut/spring-boot-guide)
[Get?Started](#Spring)
渲染效果如下：
封面的內(nèi)容可以使用html或者markdown語法編寫，自由度極高。
?封面的背景顏色是隨機切換的，可以使用設置固定的背景色
?docsify項目部署
主要介紹GitHub Pages和騰訊云COS的部署，其他類似于Coding Pages或者阿里云OSS的部署方式等等可以參照下面介紹的兩種方式進行部署。
部署在GitHub Pages
先建一個Github倉庫，把項目文件推送上去：
點右上角紅圈中的Settings按鈕，配置Github Pages：
保存完畢之后，配置一下自定義的域名解析，也就是把域名解析到項目的Github Pages中，然后就可以通過自定義域名訪問此項目。
?當然，Github也為每個賬戶提供一個免費的子域名：賬號.github.io，需要建一個命名為"賬號.github.io"倉庫，把項目文件推上到此倉庫，再配置一下Github Pages的屬性即可通過"賬號.github.io"訪問此項目。
?部署在騰訊云COS
筆者已經(jīng)把一個子域名spring.throwx.cn解析到騰訊云COS的docsify項目中，過程很簡單。先創(chuàng)建一個對象存儲的桶設置為「公有讀私有寫」：
接著把整個docsify項目中的文件拷貝到桶中，「index.html文件必須在桶的根目錄」：
然后配置桶的基本配置 - 靜態(tài)網(wǎng)站中的索引文檔(主頁)如下：
做完這一步之后，就可以通過COS的公網(wǎng)域名訪問docsify項目。最后再把子域名解析到COS的內(nèi)網(wǎng)域名即可通過自定義的子域名訪問該項目，效果如下：
?騰訊云新用戶有六個月的COS免費試用特權，建議嘗鮮。
?小結
如果喜歡markdown語法，并且希望用寫博客的姿勢去編寫文檔，或者用寫文檔的姿勢去寫博客，可以嘗試一下docsify，你應該會喜歡上這個優(yōu)秀的開源工具的。
參考資料：
- docsify官方文檔：https://docsify.js.org
示例項目倉庫：
- Github：https://github.com/zjcscut/docsify-demo
示例項目在線演示入口：
- 騰訊云：https://spring.throwx.cn
(本文完 c-2-d e-a-20200902)
總結
以上是生活随笔為你收集整理的.net编写抽奖的文档_使用开源文档工具docsify，用写博客的姿势写文档的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 华阴包子是发面吗
- 下一篇： mos管结电容等效模型_MOS管硬开关震