用 Sphinx 搭建部落格時,如何自定義外掛?
之前有不少同學看過我的個人部落格,也根據我寫的教程完成了自己個人站點的搭建。
為防有的同學不清楚 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 會做三件事:
- 判斷頁面是否載入完成,載入完成後才執行;
- 給 class 為 rst-content 的 div 加一個 id 屬性:container;
- 根據網頁地址判斷是否文章頁面,是則執行,否則不執行;
如果你不想自己寫,可以在我的公眾號後臺回覆“導流”,直接用我寫好的js檔案。
獲取到的js檔案需要放在固定的路徑下:source/_static/js/
(如果沒有此路徑就手動建立),然後修改 conf.py
html_static_path = ['_static']
html_js_files = [
'js/readmore.js',
]
按理說,這樣就已經大功告成了。
但是別忘了,我們是用 readthedocs 生成我們的部落格頁面的。
為此,我們同樣也要在 readthedocs 進行相關的配置。
- 改 CPython 2.x 為 CPython 3.x
- 指定我們的本地最新生成的 requirements.txt
(注:使用 pip freeze >requirements.txt 生成)
同時你如果之前是看過我寫的教程,使用過我的中文檢索外掛,那你要注意了。
此前這個外掛是基於 Python 2.x 寫的,現在我們切換成 Sphinx 專案切換成 Python 3.x ,所以這裡的程式碼也要對應修改。
改動也不大,只要把exts/smallseg.py
這個檔案裡的 decode 相關的程式碼全部去掉即可。
一切按照上面的步驟全部設定完成後,提交Github後,再次從 readthedocs 構建就可以看到效果了。
對於這個功能,我幾點要說明:
- 對於經常看我部落格的同學,如果你已經關注我的公眾號,仍然需要你驗證一下。
- 如果你換電腦、瀏覽器,會需要你重新驗證,這點希望大家包容。
第二個外掛:百度統計
作用:用於收集個人網站的訪問資料。
有了上面的經驗,現在我們知道如何在頁面中外掛自定義 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等),每篇文章的點選量(你就知道哪篇是爆款?),每天有多少老訪問客,多少新訪客等等,更多維度的資料你可以自己去體驗一下。