用 Sphinx 搭建博客時，如何自定義插件？

以前有很多同窗看過個人我的博客（python-online.cn），也根據我寫的教程完成了本身我的站點的搭建。

點此：使用 Python 30分鐘 教你快速搭建一個博客

爲防有的同窗不清楚 Sphinx ，這裏仍是作下簡單的介紹。

它是一個可以把一組 reStructuredText 或者 Markdown 格式的文件轉換成各類輸出格式，並且自動地生成交叉引用，生成目錄等的一個文檔編排工具。

不得不說，它的排版功能強大、很是清晰，顔值很是高。

可是使用這個方法搭建的博客，一直有一個痛點，就是沒法自定義頁面，自由度很是的低（和 WordPress 真的無法比）。

這就致使我一直不知道到底有沒有人訪問個人網站？

他們都是從哪來訪問的，Google 仍是 百度？

每篇文章都有多少人訪問，哪篇文章最受歡迎？

我一直在個人博客上貼上個人公衆號二維碼，可到底所以關注個人人有多少呢？

所以我一直但願能找到一個可以收集網站訪問數據、而且能將博客上的訪客引導到公衆號上來的方法。

終於在昨天，我找到了，並花了兩天的時間成功上線。

方法就是引入兩個 JavaSript 插件實現（這個在早期的 Sphinx 版本中是不支持的）。

第一個插件：導流工具

做用：這個主要用來將本身博客上流量引到本身的公衆號上。

具體是思路是：

遊客沒法閱讀博客的所有內容，由於會有一半的內容會被隱藏。就像這樣。

如想要閱讀全文，能夠點擊全文進行解鎖：用微信掃描二維碼關注個人我的公衆號，發送 more ，將獲取到的驗證碼填入以下文本框提交便可永久解鎖本博客的全部乾貨文章。

思路有了，那麼如何實現呢？

以上功能其實已經有人已經作出來並能夠提供無償使用。

你能夠在 https://openwrite.cn/ 註冊一個賬號，而後在裏面你能夠看到一個導流工具，填寫你的公衆號及引流的相關信息後，就初始化成功，得到一串js代碼。

接下來，你要作的就是將這串js接入你的博客頁面中。

因爲我去年搭建這個博客時使用的 Sphinx 的版本是 1.7 ，這個版本是不支持自定義css/js 文件的。

所以，你要使用引入這段js代碼，須要將你的 Sphinx 升級到 1.8+，我使用的是最新版本的 2.1 ，這個版本只支持 Python 3.5+。

所以在使用以前，我得先將環境的切換至 Python 3.5+。

virtualenv -p /usr/bin/python3.6 myblog
複製代碼

而後安裝 Sphinx 及相關包

pip install Sphinx sphinx-rtd-theme -i https://pypi.douban.com/simple
複製代碼

問題一

雖然如今咱們的 Sphinx 已經支持自定義js了（方法是將一個js文件以引用的方式放在 header 標籤裏）

可是 OpenWrite 要實現 閱讀全文 的效果，這個readmore.js必須放在 HTML 的尾部，意思是要等頁面加載完成後才能起做用。

這下就尷尬了。Sphinx 會將 readmore.js 放在 HTML 頂部，而要實現 閱讀全文 的效果，readmore.js 須要放在底部。因爲框架是固定的，咱們沒法對其進行定製修改。那還有什麼方法能夠補救呢？

個人方案是：在 readmore.js 中加入邏輯，當頁面加載完成後再運行。

問題二

若想 readmore.js 起做用，前提是你的文章的正文div中須要有一個id=‘container’屬性， 而這個 Sphinx 是不會生成的。

這樣的話，這個動態添加 id 屬性的工做也只能交由 readmore.js 來作了。

問題三

由 Sphinx 生成的的全部頁面都會加引入這個 readmore.js 插件，這就致使全部的頁面（包括首頁，索引頁）都會有 閱讀全文 的限制。這明顯是不合理的。

爲了解決這個問題，我想的是在 readmore.js 中，根據 url 進行判斷，只有文章頁面纔有限制，而其餘的頁面則不受限制。

總結一下，這個 readmore.js 會作三件事：

1. 判斷頁面是否加載完成，加載完成後才執行；
2. 給 class 爲 rst-content 的 div 加一個 id 屬性：container；
3. 根據網頁地址判斷是否文章頁面，是則執行，不然不執行；

若是你不想本身寫，能夠在個人公衆號後臺回覆「導流」，直接用我寫好的js文件。

獲取到的js文件須要放在固定的路徑下： source/_static/js/ （若是沒有此路徑就手動建立），而後修改 conf.py

html_static_path = ['_static']

html_js_files = [
    'js/readmore.js',
]
複製代碼

按理說，這樣就已經大功告成了。

可是別忘了，咱們是用 readthedocs 生成咱們的博客頁面的。

爲此，咱們一樣也要在 readthedocs 進行相關的配置。

1. 改 CPython 2.x 爲 CPython 3.x
2. 指定咱們的本地最新生成的 requirements.txt

（注：使用 pip freeze >requirements.txt 生成）

同時你若是以前是看過我寫的教程，使用過個人中文檢索插件，那你要注意了。

此前這個插件是基於 Python 2.x 寫的，如今咱們切換成 Sphinx 項目切換成 Python 3.x ，因此這裏的代碼也要對應修改。

改動也不大，只要把 exts/smallseg.py 這個文件裏的 decode 相關的代碼所有去掉便可。

一切按照上面的步驟所有設置完成後，提交Github後，再次從 readthedocs 構建就能夠看到效果了。

對於這個功能，我幾點要說明：

1. 對於常常看我博客的同窗，若是你已經關注個人公衆號，仍然須要你驗證一下。
2. 若是你換電腦、瀏覽器，會須要你從新驗證，這點但願你們包容。

第二個插件：百度統計

做用：用於收集我的網站的訪問數據。

有了上面的經驗，如今咱們知道如何在頁面中插件自定義 js 代碼。

那我就想有沒有那種能夠經過引入 js 插件來收集網站的訪問數據呢？

這種工具應該很多，而我使用的是百度家的產品 - 百度統計 。

它能夠幫咱們收集網站訪問數據，提供流量趨勢、來源分析、轉化跟蹤、頁面熱力圖、訪問流等多種統計分析服務。

那怎麼使用呢？

首先使用你的百度賬號登錄 百度統計。

而後在網站列表新增一個你的網站，個人信息以下：

填寫完成，就能夠獲取一段屬於你的網站的專屬 js 代碼（下面第一步）。

第二步內容，是教你如何安裝這段 js 代碼。

將這段代碼內容寫入一個單獨的 js 文件：baidutongji.js

var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?xxxxxxxx";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
複製代碼

並修改 conf.py 後，提交至你的 Github。

html_js_files = [
    'js/readmore.js',
    'js/baidutongji.js'
]
複製代碼

一切完成後，就能夠去 readthedocs 重建構建。

構建完成後，去執行第三步，代碼安裝檢查。像我下面這樣，就是安裝完成了。

這個插件安裝完成後，若是你的網站有流量，能夠過個一個小時，點擊一下查看報告查看你網站的詳細訪問數據。

數據真的很是全面，你能夠知道，訪客都是從哪裏訪問（直接訪問，Google等），每篇文章的點擊量（你就知道哪篇是爆款？），天天有多少老訪問客，多少新訪客等等，更多維度的數據你能夠本身去體驗一下。

​