logo
搜索
我的图书馆

发文章

发文工具

其他工具

留言交流
搜索
分享

WordPress+Markdown+为知笔记，实现高质量笔记和博客

 爽行天下丶 2015-06-24

 本文写给：和我一样想要有一套操作容易、使用方便、兼容性好的 高质量个人知识管理和博客 实现方案的人。

欢迎通过此链接注册为知笔记来支持本人：https://note./i/1fe81312

需求

平时学东西时，喜欢写一些笔记，一方面作为记录，时间久了不记得了可以看看，另一方面发到网上或许能帮到别人。之前用CSDN，发现博客编辑实在是非常难用，索性自己建了一个WordPress的站点，每次发布完再复制粘贴到CSDN博客。

记笔记我用的为知笔记，为知笔记有个博客离线发布的功能，我在本地写好的笔记，可以直接一键发送到博客，非常方便。但是由于兼容性问题，博客发布后显示效果不是那么理想，尤其是代码在本地为知笔记有自己的一套代码高亮系统，WordPress和CSDN又分别有不同的代码高亮系统，发布时还是不得不手动做不少修改。

由于前段时间有人决定开始写博客，然后问了我一些问题，包括博客怎么做到编辑方便又能很好的排版，同时可以在本地有一份方便管理的笔记，我就给他推荐了为知笔记、CSDN、WordPress还有Markdown，让他自己了解下再决定。Markdown是一种实现高质量文章的好方法，由于为知笔记支持Markdown，之前我也试过，但是发布到博客显示效果不是很好，而且也没有很大需求。这次重新研究了一番，最后总结除了一套个人感觉比较好的实现高质量知识管理和博客的方法，总结成这篇文章。

基础知识与准备工作

为知笔记相关说明

这里主要做几点说明：

  • 为知笔记在笔记名后增加.md，打开后在编辑模式下为Markdown源文件，在阅读模式下即为经过Markdown渲染后的效果（如果不显示渲染后的效果，可以关掉笔记重新打开）。
  • 使用Markdown的笔记，在点击发布到博客时，需要勾选"使用Markdown渲染"的选项。
  • 使用Markdown渲染后发布到WordPress的文章，只含HTML内容，不含CSS样式。CSS样式由WordPress主题中的style.css决定。
  • 经过对输出HTML的分析，为知笔记Markdown中的代码高亮，由Google开源项目prettyprint实现。

利用为知笔记Markdown+自定义CSS，高质量代码编辑So Easy

前面做了大量准备工作，下面要说的就是本文的核心内容。注意如果你的WordPress用了其他代码高亮插件，建议先将其停用，然后再进行操作，以免发生冲突。

我们可以用为知笔记写一个简单的Markdown笔记，例如：

  1. ##标题2
  2. ###标题3
  4. ***
  6. - 列表1
  7. - 列表2
  9. ***
  11. ```
  12. #include <stdio.h>
  14. int main() {
  15.     printf("Hello World!\n");
  16.     return 0;
  17. }
  18. ```

保存为test.md，即可在为知笔记中看到渲染后的效果。

将其发布到WordPress博客，查看网页源代码，可以看到为知笔记输出的HTML结果：

  1. <h2 id="-2">标题2</h2>
  2. <h3 id="-3">标题3</h3>
  3. <hr>
  4. <ul>
  5. <li>列表1</li>
  6. <li>列表2</li>
  7. </ul>
  8. <hr>
  9. <pre class="prettyprint linenums language-undefined prettyprinted" style="">
  10.     <ol class="linenums" style="padding-left: 0px;">
  11.         <li style="list-style-type: none; padding-left: 0px;" class="L0">
  12.             <code><span class="com">#include</span><span class="pln"> </span><span class="str"><stdio.h></span></code>
  13.         </li>
  14.         <li style="list-style-type: none; padding-left: 0px;" class="L1"><code></code></li>
  15.         <li style="list-style-type: none; padding-left: 0px;" class="L2">
  16.             <code><span class="kwd">int</span><span class="pln"> main</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span></code>
  17.         </li>
  18.         <li style="list-style-type: none; padding-left: 0px;" class="L3">
  19.             <code><span class="pln">    printf</span><span class="pun">(</span><span class="str">"Hello World!\n"</span><span class="pun">);</span></code>
  20.         </li>
  21.         <li style="list-style-type: none; padding-left: 0px;" class="L4">
  22.             <code><span class="pln">    </span><span class="kwd">return</span><span class="pln"> </span><span class="lit">0</span><span class="pun">;</span></code>
  23.         </li>
  24.         <li style="list-style-type: none; padding-left: 0px;" class="L5">
  25.             <code><span class="pun">}</span></code>
  26.         </li>
  27.     </ol>
  28. </pre>

但是我们看到的显示效果可能并不好，原因在于我们的WordPress主题中的CSS没有针对Markdown进行优化完善。下面的问题就很简单了，就是改CSS。根据个人喜好，网站风格等，将CSS进行修改完善，也就是修改主题中的style.css文件。

对于h1，h2，h3，ul，ol，li，hr这些常规标签样式的修改，倒没什么问题，而且通常主题自身就含有这些标签的样式。要注意的是，这里的代码高亮用的是prettyprint的风格，因此，我们可以下载到prettyprint插件，并将其CSS复制到我们的CSS中。

最后经过测试，prettyprint的css还是有一些问题，可能是因为版本或是其他css的原因。经过了反复的修改，下面给出我使用的css（代码高亮部分），由于不同主题中的元素差异，并不能保证在其他网站也能使用，仅供参考使用。

  1. code .pln{color:#000}
  2. code .str{color:#080}
  3. code .kwd{color:#24F}
  4. code .com{color:#78C}
  5. code .typ{color:#24F}
  6. code .lit{color:#066}
  7. code .tag{color:#008}
  8. code .atn{color:#606}
  9. code .atv{color:#080}
  10. code .fun{color:#F00}
  11. code .dec,.var{color:#606}
  12. code .pun,.opn,.clo{color:#333}
  13. .single-content pre,.single-content code{font-family:Consolas,'Liberation Mono',Menlo,Courier,monospace!important}
  14. .single-content p code{margin:0 2px;padding:2px 5px;border:1px solid #eaeaea;background-color:#f8f8f8;border-radius:3px}
  15. .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}
  16. .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
  1. #include <stdio.h>
  3. int main() {
  4.     printf("Hello World!\n");
  5.     return 0;
  6. }

一些问题

在这个过程中，遇到了很多问题，特别是对CSS不了解的情况下，更是困难重重。下面进行一些列举，或许能对别人有所帮助。

  1. 为知笔记中Markdown渲染后，代码不缩进。解决这个问题的方法是，编写代码时用空格做缩进而不是tab符号，Markdown会自动忽略tab符号（除非用HTML转义字符书写）。

  2. 代码中的空行不显示

    查看代码可以看到，代码中的空行会被转换成<li style="list-style-type: none; padding-left: 0px;" class="L1"><code></code></li>，code标签中为空，然后会直接不显示，于是所有代码中的空行直接消失不见了。我的解决方法是，给每个li元素设置一个最小高度min-height，这个高度和行高line-height相同，这样即使code标签不显示，空行还是会保证一行的最小高度。

  3. 代码不显示行号

    行号显示是利用有序列表的li标签自身序号实现的，需要设置属性list-style-type:decimal!important。注意这里加了后缀!important，因为生成的HTML中，标签li被自动添加了这个属性且为内联式，只有在CSS中添加!important，才能让CSS设置的值生效，而不是被内联式的样式覆盖掉。另外要注意的是，如果li元素使用了overflow:hidden属性，也会导致前面的标号不显示；这时要么去掉overflow属性，要么再添加一个list-style-position:inside属性即可。

  4. 为知笔记的非VIP用户每次都会在文末生成一个 来自为知笔记 的链接。

    这个是用于为知笔记推广的链接，通过这个链接注册为知笔记还可以增加积分，建议保留。如果一定要去掉，特别是强迫症用户，又不想每次手动在WordPress中编辑，可以通过在主题的functions.php文件中添加如下php代码。这段代码通过添加钩子，在文章保存到数据库前，对文章内容进行了正则替换，将包含为知笔记链接的内容自动替换为空字符串了。

    1. function content_replace($data) {
    2. // 正则字符串写法为'/reg_exp/', /需要转义成\/
    3. $data = preg_replace("/<div><a.*http:\/\/www.\/.*<\/a><\/div>/", "", $data);
    4. return $data;
    5. }
    6. add_filter( 'content_save_pre', 'content_replace');

  5. 文章一旦发布到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等插件，在插入代码时也是相当的郁闷，根本不敢随便切换到图形界面。。。

  6. 固定链接的问题。有人喜欢手动给每篇文章设置好看的固定链接，即使用%postname%字段作为文章网址。而用为知笔记的离线发布，会自动将文章标题作为postname从而生成链接。这时可以先发布再修改固定链接，修改时，直接在快速编辑中修改即可，避免进入编辑界面影响文章内容。

添加LaTeX公式支持（使用MathJax）

为知笔记的Markdown中支持插入LaTeX公式，输出由MathJax渲染。只要在编辑时，使用$或$$符号包含LaTeX公式代码，即可自动转换成公式。

实例

例如下面的Markdown代码

  1. > ###Latex公式测试
  2. 行内公式 $ \delta = \beta / (\alpha + 1)$
  3. 行间公式
  4. $$
  5. \frac{O}{I}  \approx \frac{A}{1+AF}
  6. $$
  7. 上下标 $$ U_o = A^2 * ( U_+ - U_- ) $$
  8. 积分
  9. $$ \int_1 ^2 sin x dx $$
  10. 方程组
  11. $$
  12. \begin{aligned}
  13. \dot{x} & = \sigma(y-x) \\
  14. \dot{y} & = \rho x - y - xz \\
  15. \dot{z} & = -\beta z + xy
  16. \end{aligned}
  17. $$

最终显示效果如下。

Latex公式测试

行内公式 δ=β/(α+1)
行间公式

OI≈A1+AF


上下标

Uo=A2?(U+?U?)


积分

∫21sinxdx


方程组

=σ(y?x)

插入专用字体

需要注意的是，要想用MathJax达到最佳的显示效果，需要使用专用字体，可在主题的CSS文件中添加以下代码（这段代码从MathJax官网的页面源文件取得）。

  1. @font-face {font-family: MathJax_Main; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Regular.otf?rev=2.5.0') format('opentype')}
  2. @font-face {font-family: MathJax_Main-bold; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Bold.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Bold.otf?rev=2.5.0') format('opentype')}
  3. @font-face {font-family: MathJax_Main-italic; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Main-Italic.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Main-Italic.otf?rev=2.5.0') format('opentype')}
  4. @font-face {font-family: MathJax_Math-italic; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Math-Italic.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Math-Italic.otf?rev=2.5.0') format('opentype')}
  5. @font-face {font-family: MathJax_Caligraphic; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Caligraphic-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Caligraphic-Regular.otf?rev=2.5.0') format('opentype')}
  6. @font-face {font-family: MathJax_Size1; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size1-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size1-Regular.otf?rev=2.5.0') format('opentype')}
  7. @font-face {font-family: MathJax_Size2; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size2-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size2-Regular.otf?rev=2.5.0') format('opentype')}
  8. @font-face {font-family: MathJax_Size3; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size3-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/otf/MathJax_Size3-Regular.otf?rev=2.5.0') format('opentype')}
  9. @font-face {font-family: MathJax_Size4; src: url('http://cdn./mathjax/latest/fonts/HTML-CSS/TeX/woff/MathJax_Size4-Regular.woff?rev=2.5.0') format('woff'), url('http://cdn./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./blog/2009/10/13/font-face-and-performance/

为了避免这种情况，可将上述CSS代码写在一个独立的文件mathjax.css中，然后利用jQuery进行判断，如果页面中用到了MathJax，就在<head>标签中添加CSS的引用，然后才从这段CSS加载字体。jQuery大致写法如下，其中url为MathJax的CSS文件mathjax.css的URL地址。

  1. function f_mathjax() {
  2.     if ($(".MathJax").length > 0) {
  3.         var url = 'http://www./css/mathjax.css';
  4.         $("head").append('<link rel="stylesheet" type="text/css" href="'+url+'"/>');
  5.     }
  6. }
  8. $(document).ready(function() { 
  9.     f_mathjax();
  10. });

一个问题

我遇到的一个问题是，公式显示效果不好，分数的横线直接不显示了。经过一步一步的排查，最后终于发现问题出在我的网站CSS中有一个属性line-height:1.8，影响了公式的正常显示。于是添加下面的CSS即解决了问题。

  1. .MathJax{line-height:1}

对比

其他WordPress代码高亮插件

网上有各种五花八门的WordPress代码高亮插件，使用起来其实也很郁闷，也是我的切身体会。例如这篇文章中提到的就是之前我用WP-Syntax插入代码的过程，需要相当小心才行，并且每次插入一段代码，都要手工输入一段HTML，相比Markdown直接输入简单的符号即可插入代码，实在是麻烦多了。尤其是对于一些需要对代码进行解释的情况，例如本文，用Markdown可以非常轻松的实现代码段和普通文本的混合编辑。

《文章编辑规范》 http://www./wp-article-edit

常规Markdown插入图片不方便

为知笔记的Markdown有个先天优势，插入图片非常方便，不需要先把图片上传到某个地方然后用Markdown引用，而只需要直接插入笔记中即可。发布时，会自动上传每张图片到博客网站。

代码高亮：性能、易用性等

很多代码高亮插件都是在页面加载时对文章中pre标签里面的代码进行处理，典型的就是用javascript实现。本方法利用Markdown渲染后再发布，不需要用javascript处理，好处是提高了性能，不需要在加载页面时执行任何额外代码，也不用任何插件，直接用普通的CSS搞定了代码高亮。而且复制到任何地方，例如CSDN博客，都不用担心代码高亮不兼容（因为复制的就是处理后的代码）。缺点是在WordPress中修改代码不会高亮，只能通过本地为知笔记修改，Markdown重新渲染然后发布。

一次编辑，多个平台同步

此方法只需要在本地编辑好，既是个人笔记，又可以一键发布到WordPress博客。如果需要发布到CSDN，还可以直接从WordPress博客复制粘贴过去（CSDN自带的HTML编辑器实在不好用）。并且这一切永远是高质量的，因为Markdown就是为编写高质量文档而生。

欢迎通过此链接注册为知笔记来支持本人：https://note./i/1fe81312

    本站是提供个人知识管理的网络存储空间，所有内容均由用户发布，不代表本站观点。请注意甄别内容中的联系方式、诱导购买等信息，谨防诈骗。如发现有害或侵权内容，请点击一键举报。
    转藏 分享 献花（0）

    来自： 爽行天下丶 > 《markdown》

    举报/认领

    0条评论

    发表

    请遵守用户 评论公约

    类似文章 更多