Docute 3 創建文檔網站

1 Docute 介紹

Docute 本質上就是一個 JavaScript 文件，它可以獲取 Markdown 文件並將它們呈現爲單頁面應用。

它完全由運行時驅動，因此並不涉及服務端組件，這就意味着沒有構建過程。你只需創建一個 HTML 文件和一堆 Markdown 文檔，你的網站就差不多完成了！

目前 Docute 已經更新到第 4 版啦，而且很不錯，如果想使用它，可以直接去看 Docute 4，如果以後有時間或者有機會再更最新的 Docute 的使用，不過官網已經很詳細了，相信你也能看的出來，由於我起步於 Docute 3，有感情了，所以會在這一版本上做大量的文檔使用說明以及優化！以我學習《算法與數據結構》做一份文檔舉例，所有優化內容都基於現在的需要！

那麼現在你會問，docute 是如何工作的呢？

簡而言之：URL 是 API。

訪問你的 URL 時，會獲取並呈現相應的 markdown 文件：

/         => /README.md
/foo      => /foo.md
/foo/     => /foo/README.md
/foo/bar  => /foo/bar.md

2 快速開始

2.1 手動創建文件

在本地新建一個文件夾，比如： algorithm-data-structure/docs 新建文件

.
├── .nojekyll
├── index.html
└── README.md

目錄結構解釋：

index.html # 入口文件
README.md # 會做爲主頁內容渲染，我寫入了 Hello
.nojekyll # 用於阻止 GitHub Pages 會忽略掉下劃線開頭的文件，就直接爲空文件就好

index.html 寫入：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0" />
  <title>EnjoyToShare - Notes</title>
  <!-- docute 的 CSS -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docute@3/dist/docute.css">
</head>
<body>
  <div id="app"></div>
  <!-- 加載 docute 的 js 庫 -->
  <script src="https://cdn.jsdelivr.net/npm/docute@3/dist/docute.js"></script>
    <!-- 你也可以把包含 $config 配置的腳本放到單獨的文件裏 -->
  <!-- 比如 config.js -->
  <script>
    docute.init({
      // 配置...
    })
  </script>
</body>
</html>

然後你可以使用以下命令將此文件夾作爲計算機上的靜態網站展示：

Node.js: npm i -g serve && serve .
Python: python -m SimpleHTTPServer
Golang: caddy
… 或任何靜態 web 服務器

效果如下：

2.2 自動創建文件

當然這一步也可以不用做，依舊可以使用 npm i -g serve && serve . 啓動服務器，不過我爲了使用方便啓動，所以還是使用了這一步。

1 第一步：使用 docute-cli 初始化環境

方式一：用 npm 安裝:

npm i -g docute-cli

方式二：用 Yarn 安裝

yarn global add docute-cli

如圖：

2 第二步：使用 docute init 生成 docs，文件裏有以下三個文件，就是手動創建的那三個喲

然後就可以使用 docute docs 啓動服務啦！

效果如下：

3 自定義定製

3.1 配置文件

執行 docute init 後你的文檔目錄會有一個 config.js 配置文件:

docute.init({
  // 配置...
})

不妨把它拿出來，單獨創建一個文件，叫 config.js ，然後寫入：

docute.init({
  // 配置...
})

然後在 index.html 引入：

<script src="./config.js"></script>

3.2 首頁

文檔目錄裏的 README.md 文件會渲染爲文檔首頁，但有時你可能會想使用其它文件。比如你將 ./docs 目錄裏的文件作爲 github pages 使用的時候你可能想直接使用項目根目錄裏的 README.md，你可以通過配置指向該文件：

docute.init({
  // 項目根目錄裏的 README.md
  home: 'https://github.com/wugenqiang/algorithm-data-structure/blob/master/README.md'
})

3.3 Landing 頁面

你可以開啓 landing 選項來啓用 Landing 頁面:

docute.init({
  // true 將會默認使用 `landing.html`，也可以寫成 landing: 'landing.html',
  landing: true,
  // 也可以用自定義頁面
  landing: '_my-landing.html',
  // 當然 markdown 文件也可以
  landing: 'landing.md'
})

如果你開啓了這個功能，Landing 頁面的路由將是 /，而文檔的首頁將改爲用 /home 訪問。

你不能在動態添加的頁面裏使用 script 標籤，因爲動態添加的內容 JS 不會被瀏覽器執行。

3.4 側邊欄

想默認隱藏側邊欄，可以在 config.js 中將其設置爲 false:

docute.init({
  sidebar: false
})

或者只隱藏某個頁面的側邊欄:

---
sidebar: false
---
用 front-matter 隱藏這個頁面的側邊欄

左下角也會有個按鈕用於切換側邊欄，你也可以隱藏它:

docute.init({
  disableSidebarToggle: true
})

3.4.1 目錄表

側邊欄的目錄表 (table of contents) 是從你的 markdown 文件解析來的，我們獲取 markdown 裏的 h2 ~ h5 標題來構成這個目錄。

默認只會顯示 h2 到 h4 的標題，其它標題只有在你頁面滾動到相應區域纔會顯示，不過你可以更改最深顯示的標題層級:

docute.init({
  // 顯示 h2 到 h4 的標題
  tocVisibleDepth: 3
})

要徹底隱藏目錄表把 toc 設置爲 false 即可。

3.5 導航欄

當你有多個頁面的時候你很可能需要一個導航欄方便用戶瀏覽，你可以通過配置文件添加導航欄:

docute.init({
  nav: [
    // 首頁
    {title: '首頁', path: '/'},
    // 中文文檔
    {title: '博客', path: 'https://wugenqiang.github.io/'}
  ]
})

path 是可以指向一個外部鏈接的，如上，它就像一個普通的超鏈接一樣工作。

除此之外你也可以用 source 來指定一個自定義的 markdown 文件而不是默認的 路徑加.md 這種形式，比如 source: 'https://foo.com/bar.md'

3.5.1 圖標

圖標設置一：Icon short-hand

docute.init({
  // slug for your github repo
  repo: 'wugenqiang/algorithm-data-structure',
  // twitter username
  twitter: 'enjoytoshare',
  // the link to source file of current page
  'edit-link': 'https://github.com/wugenqiang/algorithm-data-structure/blob/master/docs/'
})

效果如下：

圖標設置二：Custom Icons

docute.init({
  icons: [{
    icon: 'github',
    label: 'Contribute on GitHub',
    link: 'https://github.com/owner/repo'
  }]
})

顯示和 Icon short-hand 一樣

3.5.2 下拉菜單

顯示一個下拉菜單以容納多個頁面:

docute.init({
  nav: [
    {title: '其他語言', type: 'dropdown', items: [
      {title: '中文', path: '/language/chinese'},
      {title: '日語', path: '/language/japanese'}
    ]}
  ]
})

3.6 代碼高亮

<!-- 代碼塊樣式優化-->
<script src="//unpkg.com/prismjs/components/prism-c.js"></script>
<script src="//unpkg.com/prismjs/components/prism-cpp.js"></script>
<script src="//unpkg.com/prismjs/components/prism-css.js"></script>
<script src="//unpkg.com/prismjs/components/prism-docker.js"></script>
<script src="//unpkg.com/prismjs/components/prism-java.js"></script>
<script src="//unpkg.com/prismjs/components/prism-javascript.js"></script>
<script src="//unpkg.com/prismjs/components/prism-json.js"></script>
<script src="//unpkg.com/prismjs/components/prism-latex.js"></script>
<script src="//unpkg.com/prismjs/components/prism-sql.js"></script>
<script src="//unpkg.com/prismjs/components/prism-markdown.js"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-scala.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-nginx.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>  
<script src="//unpkg.com/prismjs/components/prism-python.js"></script>

舉例：

def fib(n):
 a,b = 1,1
 for i in range(n-1):
  a,b = b,a+b
 return a
print fib(5)

效果：

4 使用 GitHub Pages

4.1 設置自動上傳 GitHub

建立 deploy.sh 文件，寫入：

echo '--------upload files start--------'
# 進入生成的構建文件夾
# cd ./

# git init

git add .

git status

git commit -m 'auto update https://github.com/wugenqiang/algorithm-data-structure.git'

echo '--------commit successfully--------'

git push -u https://github.com/wugenqiang/algorithm-data-structure.git master

echo '--------push to GitHub successfully--------'

修改你自己的 GitHub 倉庫地址，記得將你的文件夾使用 git init 進行初始化，才能上傳至 GitHub 中，使用一鍵自動上傳功能要保證 GitHub 中已經存在該倉庫，所以記得去 GitHub 中建立和獲取鏈接。

使用 ./deploy.sh 或者 bash deploy.sh 命令上傳即可。

上傳效果圖：

GitHub 中效果圖：

4.2 開啓 GitHub Pages

點擊 Settings：

找到 GitHub Pages

如果是在 docs 下面建立文檔網站，就如圖紅框選擇；若在主目錄下建立，選擇第一個

成功建立，通過這個地址就可訪問你的文檔網站：

比如：https://wugenqiang.github.io/algorithm-data-structure

到這裏，就初步完成文檔網站建立啦，如何繼續優化，以後需要再寫，現在就是開始寫文章咯！

5 功能優化

注：後續更新，請參考：Docute創建文檔網站

6 效果展示

算法與數據結構學習筆記

偶然之間看到大佬的說辭，我知道我需要更加努力了！（寫於 2020 - 04 - 25 ）

Docute 創建文檔網站（docute v3）

文章目錄

Docute 3 創建文檔網站

1 Docute 介紹

2 快速開始

2.1 手動創建文件

2.2 自動創建文件

3 自定義定製

3.1 配置文件

3.2 首頁

3.3 Landing 頁面

3.4 側邊欄

3.4.1 目錄表

3.5 導航欄

3.5.1 圖標

3.5.2 下拉菜單

3.6 代碼高亮

4 使用 GitHub Pages

4.1 設置自動上傳 GitHub

4.2 開啓 GitHub Pages

5 功能優化

6 效果展示

python gdal 安裝使用（Windows， python 3.6.8）

【高等數學】第 4 講泰勒展開

【高等數學】第 3 講導數

【高等數學】第 5 講偏導數

【高等數學】第 6 講積分

docsify 構建文檔網站之定製功能（全網最全）

Mac下配置sublime實現LaTeX

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結