docsify神奇的文件網站生成工具

Drl龍發表於2019-03-14
網站

原文連結

個人部落格-歡迎訪問

docsify 是一個動態生成文件網站的工具。不同於 GitBook、Hexo 的地方是它不會生成將 .md 轉成 .html 檔案，所有轉換工作都是在執行時進行。

這將非常實用，如果只是需要快速的搭建一個小型的文件網站，或者不想因為生成的一堆 .html 檔案“汙染” commit 記錄，只需要建立一個 index.html 就可以開始寫文件而且直接部署在 GitHub Pages。

docsify

特性

  • 無需構建，寫完文件直接釋出
  • 容易使用並且輕量 (~19kB gzipped)
  • 智慧的全文搜尋
  • 提供多套主題
  • 豐富的 API
  • 支援 Emoji
  • 相容 IE10+
  • 支援 SSR (example)

快速開始

推薦安裝 docsify-cli 工具，可以方便建立及本地預覽文件網站。

npm i docsify-cli -g
複製程式碼

初始化專案

如果想在專案的 ./docs 目錄裡寫文件，直接通過 init 初始化專案。

docsify init ./docs
複製程式碼

開始寫文件

初始化成功後，可以看到 ./docs 目錄下建立的幾個檔案

  • index.html 入口檔案
  • README.md 會做為主頁內容渲染
  • .nojekyll 用於阻止 GitHub Pages 會忽略掉下劃線開頭的檔案 直接編輯 docs/README.md 就能更新網站內容，當然也可以寫多個頁面。

本地預覽網站

執行一個本地伺服器通過 docsify serve 可以方便的預覽效果，而且提供 LiveReload 功能，可以讓實時的預覽。預設訪問 http://localhost:3000 。

docsify serve docs
複製程式碼

更多命令列工具用法，參考 docsify-cli 文件。

手動初始化

如果不喜歡 npm 或者覺得安裝工具太麻煩，我們其實只需要直接建立一個 index.html 檔案。

// index.html

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>
複製程式碼

如果系統裡安裝 Python 的話，也可以很輕易的啟動一個靜態伺服器。

cd docs && python -m SimpleHTTPServer 3000
複製程式碼

Loading 提示

初始化時會顯示 Loading... 內容，你可以自定義提示資訊。

// index.html

  <div id="app">載入中</div>
複製程式碼

如果更改了 el 的配置，需要將該元素加上 data-app 屬性。

// index.html

  <div data-app id="main">載入中</div>

  <script>
    window.$docsify = {
      el: '#main'
    }
  </script>

複製程式碼

示例

這是一份docsify開發的文件歡迎點選檢視

更加詳細的設定配置參考官方文件

相關文章