本文寫給:和我一樣想要有一套操作容易、使用方便、兼容性好的 高質量個人知識管理和博客 實現方案的人。
歡迎通過此鏈接註冊爲知筆記來支持本人:https://note.wiz.cn/i/1fe81312
需求
平時學東西時,喜歡寫一些筆記,一方面作爲記錄,時間久了不記得了可以看看,另一方面發到網上或許能幫到別人。之前用CSDN,發現博客編輯實在是非常難用,索性自己建了一個WordPress的站點,每次發佈完再複製粘貼到CSDN博客。
記筆記我用的爲知筆記,爲知筆記有個博客離線發佈的功能,我在本地寫好的筆記,可以直接一鍵發送到博客,非常方便。但是由於兼容性問題,博客發佈後顯示效果不是那麼理想,尤其是代碼在本地爲知筆記有自己的一套代碼高亮系統,WordPress和CSDN又分別有不同的代碼高亮系統,發佈時還是不得不手動做不少修改。
由於前段時間有人決定開始寫博客,然後問了我一些問題,包括博客怎麼做到編輯方便又能很好的排版,同時可以在本地有一份方便管理的筆記,我就給他推薦了爲知筆記、CSDN、WordPress還有Markdown,讓他自己瞭解下再決定。Markdown是一種實現高質量文章的好方法,由於爲知筆記支持Markdown,之前我也試過,但是發佈到博客顯示效果不是很好,而且也沒有很大需求。這次重新研究了一番,最後總結除了一套個人感覺比較好的實現高質量知識管理和博客的方法,總結成這篇文章。
基礎知識與準備工作
-
瞭解Markdown的使用
可參考《Markdown簡介和基本語法》 http://www.paincker.com/markdown
-
安裝和熟悉爲知筆記的使用,包括離線發佈功能和Markdown的使用
可參考
- 《爲知筆記:優秀國產知識管理軟件的使用心得》 http://www.paincker.com/wiz-note
- 《爲知筆記離線博客發佈功能》 http://www.paincker.com/wiz-blog
-
搭建自己的WordPress博客
可參考《網站搭建從零開始》系列博客: http://www.paincker.com/category/mobile-web/website-primer
-
簡單瞭解HTML、CSS基本知識
可參考《w3school 在線教程》 http://www.w3school.com.cn/
-
簡單瞭解WordPress主題的製作
可參考《WordPress主題製作全過程》系列博客 http://www.ludou.org/create-wordpress-themes-prepare.html
-
瞭解LaTeX數學公式常用語法
LaTeX可以參考《一份其實很短的 LaTeX 入門文檔》
http://liam0205.me/2014/09/08/latex-introduction/
LaTeX數學公式語法可以需要時再從網上搜索
爲知筆記相關說明
這裏主要做幾點說明:
-
爲知筆記在筆記名後增加
.md
,打開後在編輯模式下爲Markdown源文件,在閱讀模式下即爲經過Markdown渲染後的效果(如果不顯示渲染後的效果,可以關掉筆記重新打開)。 - 使用Markdown的筆記,在點擊發布到博客時,需要勾選"使用Markdown渲染"的選項。
-
使用Markdown渲染後發佈到WordPress的文章,只含HTML內容,不含CSS樣式。CSS樣式由WordPress主題中的
style.css
決定。 - 經過對輸出HTML的分析,爲知筆記Markdown中的代碼高亮,由Google開源項目prettyprint實現。
利用爲知筆記Markdown+自定義CSS,高質量代碼編輯So Easy
前面做了大量準備工作,下面要說的就是本文的核心內容。注意如果你的WordPress用了其他代碼高亮插件,建議先將其停用,然後再進行操作,以免發生衝突。
我們可以用爲知筆記寫一個簡單的Markdown筆記,例如:
##標題2
###標題3
***
- 列表1
- 列表2
***
```
#include <stdio.h>
int main() {
printf("Hello World!\n");
return 0;
}
```
保存爲test.md,即可在爲知筆記中看到渲染後的效果。
將其發佈到WordPress博客,查看網頁源代碼,可以看到爲知筆記輸出的HTML結果:
<h2 id="-2">標題2</h2>
<h3 id="-3">標題3</h3>
<hr>
<ul>
<li>列表1</li>
<li>列表2</li>
</ul>
<hr>
<pre class="prettyprint linenums language-undefined prettyprinted" style="">
<ol class="linenums" style="padding-left: 0px;">
<li style="list-style-type: none; padding-left: 0px;" class="L0">
<code><span class="com">#include</span><span class="pln"> </span><span class="str"><stdio.h></span></code>
</li>
<li style="list-style-type: none; padding-left: 0px;" class="L1"><code></code></li>
<li style="list-style-type: none; padding-left: 0px;" class="L2">
<code><span class="kwd">int</span><span class="pln"> main</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span></code>
</li>
<li style="list-style-type: none; padding-left: 0px;" class="L3">
<code><span class="pln"> printf</span><span class="pun">(</span><span class="str">"Hello World!\n"</span><span class="pun">);</span></code>
</li>
<li style="list-style-type: none; padding-left: 0px;" class="L4">
<code><span class="pln"> </span><span class="kwd">return</span><span class="pln"> </span><span class="lit">0</span><span class="pun">;</span></code>
</li>
<li style="list-style-type: none; padding-left: 0px;" class="L5">
<code><span class="pun">}</span></code>
</li>
</ol>
</pre>
但是我們看到的顯示效果可能並不好,原因在於我們的WordPress主題中的CSS沒有針對Markdown進行優化完善。下面的問題就很簡單了,就是改CSS。根據個人喜好,網站風格等,將CSS進行修改完善,也就是修改主題中的style.css文件。
對於h1,h2,h3,ul,ol,li,hr
這些常規標籤樣式的修改,倒沒什麼問題,而且通常主題自身就含有這些標籤的樣式。要注意的是,這裏的代碼高亮用的是prettyprint的風格,因此,我們可以下載到prettyprint插件,並將其CSS複製到我們的CSS中。
最後經過測試,prettyprint的css還是有一些問題,可能是因爲版本或是其他css的原因。經過了反覆的修改,下面給出我使用的css(代碼高亮部分),由於不同主題中的元素差異,並不能保證在其他網站也能使用,僅供參考使用。
code .pln{color:#000}
code .str{color:#080}
code .kwd{color:#24F}
code .com{color:#78C}
code .typ{color:#24F}
code .lit{color:#066}
code .tag{color:#008}
code .atn{color:#606}
code .atv{color:#080}
code .fun{color:#F00}
code .dec,.var{color:#606}
code .pun,.opn,.clo{color:#333}
.single-content pre,.single-content code{font-family:Consolas,'Liberation Mono',Menlo,Courier,monospace!important}
.single-content p code{margin:0 2px;padding:2px 5px;border:1px solid #eaeaea;background-color:#f8f8f8;border-radius:3px}
.single-content ol.linenums{padding:10px 10px 10px 0!important;background-color:#f7f7f9;border:1px solid #e1e1e8;border-radius:3px;box-shadow:#fbfbfc 50px 0 0 inset,#ececf0 51px 0 0 inset}
.single-content ol.linenums li{margin:0 0 0 55px;line-height:1.5;min-height:1.5em;color:#AAA;list-style-type:decimal!important;padding-left:10px!important}
最後,在我的網站,這篇測試文章實際顯示的效果如下。如果使用的Chrome瀏覽器,你可以在右鍵-審查元素中看到我編寫的CSS實際效果。
標題2
標題3
- 列表1
- 列表2
#include <stdio.h>
int main() {
printf("Hello World!\n");
return 0;
}
一些問題
在這個過程中,遇到了很多問題,特別是對CSS不瞭解的情況下,更是困難重重。下面進行一些列舉,或許能對別人有所幫助。
-
爲知筆記中Markdown渲染後,代碼不縮進。解決這個問題的方法是,編寫代碼時用空格做縮進而不是tab符號,Markdown會自動忽略tab符號(除非用HTML轉義字符書寫)。
-
代碼中的空行不顯示
查看代碼可以看到,代碼中的空行會被轉換成
<li style="list-style-type: none; padding-left: 0px;" class="L1"><code></code></li>
,code
標籤中爲空,然後會直接不顯示,於是所有代碼中的空行直接消失不見了。我的解決方法是,給每個li
元素設置一個最小高度min-height
,這個高度和行高line-height
相同,這樣即使code
標籤不顯示,空行還是會保證一行的最小高度。 -
代碼不顯示行號
行號顯示是利用有序列表的
li
標籤自身序號實現的,需要設置屬性list-style-type:decimal!important
。注意這裏加了後綴!important
,因爲生成的HTML中,標籤li
被自動添加了這個屬性且爲內聯式,只有在CSS中添加!important
,才能讓CSS設置的值生效,而不是被內聯式的樣式覆蓋掉。另外要注意的是,如果li
元素使用了overflow:hidden
屬性,也會導致前面的標號不顯示;這時要麼去掉overflow
屬性,要麼再添加一個list-style-position:inside
屬性即可。 -
爲知筆記的非VIP用戶每次都會在文末生成一個 來自爲知筆記 的鏈接。
這個是用於爲知筆記推廣的鏈接,通過這個鏈接註冊爲知筆記還可以增加積分,建議保留。如果一定要去掉,特別是強迫症用戶,又不想每次手動在WordPress中編輯,可以通過在主題的functions.php文件中添加如下php代碼。這段代碼通過添加鉤子,在文章保存到數據庫前,對文章內容進行了正則替換,將包含爲知筆記鏈接的內容自動替換爲空字符串了。
function content_replace($data) {
// 正則字符串寫法爲'/reg_exp/', /需要轉義成\/
$data = preg_replace("/<div><a.*http:\/\/www.wiz.cn\/.*<\/a><\/div>/", "", $data);
return $data;
}
add_filter( 'content_save_pre', 'content_replace');
-
文章一旦發佈到WordPress,如果在WordPress編輯器在線進行編輯,切換到圖形界面並保存,會導致文章內容出現一些錯誤,具體的表現和原因如下。
-
尖括號及其內部代碼會被處理掉,例如
<stdio.h>
。尖括號本身容易和HTML標籤混淆,所以一般都會被轉換成轉義字符。這個通常是因爲其他代碼高亮插件沒有被關掉,例如WP-Syntax等。 -
代碼縮進格式被刪除。原因是代碼縮進用的是空格,在WordPress的圖形編輯器中,會自動忽略掉HTML中的空格。避免這個問題比較好的方法是避免使用圖形編輯器,而直接用文本編輯器。還有種辦法,在functions中,還是通過正則替換的方法,將HTML源碼中的空格替換成
,這樣就不會被圖形化編輯器去掉了。 -
代碼段落的背景混亂。還是因爲圖形編輯器,把pre標籤自動給去掉了(WordPress的圖形編輯器真是相當霸道 o(╯□╰)o )。我應對這個問題的辦法就是直接不用圖形編輯器;另外,代碼段由
pre.prettyprint
和ol.linenums
標籤包裹,我把CSS樣式全部設置給ol.linenums
了,這樣即使pre標籤被去掉,也不影響代碼的顯示。
總而言之,最大的問題就是不能輕易使用WordPress的編輯器特別是圖形編輯器對文章進行修改。如果需要修改,可以在爲知筆記中改好再重新發布(會自動判斷並編輯文章而不是新建);或者直接使用文本界面進行編輯。雖然這樣做很麻煩,但是實際上之前我用的過WP-Syntax等插件,在插入代碼時也是相當的鬱悶,根本不敢隨便切換到圖形界面。。。
-
-
固定鏈接的問題。有人喜歡手動給每篇文章設置好看的固定鏈接,即使用
%postname%
字段作爲文章網址。而用爲知筆記的離線發佈,會自動將文章標題作爲postname從而生成鏈接。這時可以先發布再修改固定鏈接,修改時,直接在快速編輯中修改即可,避免進入編輯界面影響文章內容。
添加LaTeX公式支持(使用MathJax)
爲知筆記的Markdown中支持插入LaTeX公式,輸出由MathJax渲染。只要在編輯時,使用$
或$$
符號包含LaTeX公式代碼,即可自動轉換成公式。
實例
例如下面的Markdown代碼
> ###Latex公式測試
行內公式 $ \delta = \beta / (\alpha + 1)$
行間公式
$$
\frac{O}{I} \approx \frac{A}{1+AF}
$$
上下標 $$ U_o = A^2 * ( U_+ - U_- ) $$
積分
$$ \int_1 ^2 sin x dx $$
方程組
$$
\begin{aligned}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
\end{aligned}
$$
最終顯示效果如下。
Latex公式測試
行內公式
δ=β/(α+1)
行間公式
OI≈A1+AF
上下標Uo=A2∗(U+−U−)
積分
∫21sinxdx
方程組
=σ(y−x)
插入專用字體
需要注意的是,要想用MathJax達到最佳的顯示效果,需要使用專用字體,可在主題的CSS文件中添加以下代碼(這段代碼從MathJax官網的頁面源文件取得)。
@font-face {font-family: MathJax_Main; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Regular.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Main-bold; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Bold.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Bold.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Main-italic; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Italic.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Italic.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Math-italic; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Math-Italic.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Math-Italic.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Caligraphic; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Caligraphic-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Caligraphic-Regular.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Size1; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size1-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size1-Regular.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Size2; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size2-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size2-Regular.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Size3; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size3-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size3-Regular.otf?rev=2.5.0') format('opentype')}
@font-face {font-family: MathJax_Size4; src: url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size4-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn.mathjax.org/mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size4-Regular.otf?rev=2.5.0') format('opentype')}
如果直接將這段CSS添加到主題的style.css
中,而使用MathJax的頁面比較少,在部分瀏覽器中,即使頁面中沒有使用@font-face
中的字體,也會下載字體文件,會造成一定的浪費,降低了性能。
在這篇文章中提出了這個問題,並給出了測試實例
http://www.stevesouders.com/blog/2009/10/13/font-face-and-performance/
爲了避免這種情況,可將上述CSS代碼寫在一個獨立的文件mathjax.css
中,然後利用jQuery進行判斷,如果頁面中用到了MathJax,就在<head>
標籤中添加CSS的引用,然後才從這段CSS加載字體。jQuery大致寫法如下,其中url
爲MathJax的CSS文件mathjax.css
的URL地址。
function f_mathjax() {
if ($(".MathJax").length > 0) {
var url = 'http://www.abc.com/css/mathjax.css';
$("head").append('<link rel="stylesheet" type="text/css" href="'+url+'"/>');
}
}
$(document).ready(function() {
f_mathjax();
});
一個問題
我遇到的一個問題是,公式顯示效果不好,分數的橫線直接不顯示了。經過一步一步的排查,最後終於發現問題出在我的網站CSS中有一個屬性line-height:1.8
,影響了公式的正常顯示。於是添加下面的CSS即解決了問題。
.MathJax{line-height:1}
對比
其他WordPress代碼高亮插件
網上有各種五花八門的WordPress代碼高亮插件,使用起來其實也很鬱悶,也是我的切身體會。例如這篇文章中提到的就是之前我用WP-Syntax插入代碼的過程,需要相當小心才行,並且每次插入一段代碼,都要手工輸入一段HTML,相比Markdown直接輸入簡單的符號即可插入代碼,實在是麻煩多了。尤其是對於一些需要對代碼進行解釋的情況,例如本文,用Markdown可以非常輕鬆的實現代碼段和普通文本的混合編輯。
常規Markdown插入圖片不方便
爲知筆記的Markdown有個先天優勢,插入圖片非常方便,不需要先把圖片上傳到某個地方然後用Markdown引用,而只需要直接插入筆記中即可。發佈時,會自動上傳每張圖片到博客網站。
代碼高亮:性能、易用性等
很多代碼高亮插件都是在頁面加載時對文章中pre標籤裏面的代碼進行處理,典型的就是用javascript實現。本方法利用Markdown渲染後再發布,不需要用javascript處理,好處是提高了性能,不需要在加載頁面時執行任何額外代碼,也不用任何插件,直接用普通的CSS搞定了代碼高亮。而且複製到任何地方,例如CSDN博客,都不用擔心代碼高亮不兼容(因爲複製的就是處理後的代碼)。缺點是在WordPress中修改代碼不會高亮,只能通過本地爲知筆記修改,Markdown重新渲染然後發佈。
一次編輯,多個平臺同步
此方法只需要在本地編輯好,既是個人筆記,又可以一鍵發佈到WordPress博客。如果需要發佈到CSDN,還可以直接從WordPress博客複製粘貼過去(CSDN自帶的HTML編輯器實在不好用)。並且這一切永遠是高質量的,因爲Markdown就是爲編寫高質量文檔而生。
歡迎通過此鏈接註冊爲知筆記來支持本人:https://note.wiz.cn/i/1fe81312
本文由jzj1993原創,轉載請註明來源:http://www.paincker.com/wp-markdown-wiz-blog