「Efficient Android Threading 笔记」- C1 Android Components and the Need for Multiprocessing Android RecyclerView Android Socket Programming Supporting Multiple Screens Make a Reusable UI in Android App Development 如何在 Android Studio 中包含 *.so library,并使用库中定义的方法? 使用 SpannableString 格式化字符串,实现前景色、下划线、超链接、图文混排等 如何使用 bound service 完成进程间通信? 创建自定义视图 Creating custom views 通过 Android Theme & Style 定制应用的样式 「译」Android ViewPropertyAnimator 介绍 Android Animation Interpolator - Android 动画插值器源码笔记 「译」Android Animation in Honeycomb by Chet Haase(Android 3.0系统中的动画机制) 从 Android Sample ApiDemos 中学习 android.animation API 的用法 如何学习 Android Animation? 如何实现 Android ListView「上拉加载更多」? 「译」向Big Nerd Ranch提问:为什么Fragment在Android App开发中非常重要? 分类整理我在 SegmentFault 上针对某些问题作的回答 Android Servcie 后台服务总结笔记 如何在Android设备旋转时暂存数据以保护当前的交互状态? Android Message Handler 消息处理机制总结笔记 如何获取FragmentTabHost中指定标签页的Fragment? Fragment子类必须包含一个public无参构造器 如何更新及替换ViewPager中的Fragment? 如何使用Android UI Fragment开发“列表-详情”界面? 一个Android音频文本同步的英文有声读物App的开发过程 「Android编程权威指南笔记」Android应用本地化 通过jfeinstein10/SlidingMenu实现Android侧滑菜单 为Ubuntu14.04部署Android App的Eclipse开发环境 「Android编程权威指南笔记」使用ListFragment显示列表 「Android编程权威指南笔记」SDK版本与兼容 「Android编程权威指南笔记」Android布局和组件 「Android编程权威指南笔记」UI Fragment 「Android编程权威指南笔记」Activity 第一次开发iOS App和Android的对比总结笔记 「App Training笔记」创建第一个应用 「App Training笔记」开发入门训练大纲 Android APP - 从远程FTP服务器下载文件到本地

GitHub Pages 仅支持 kramdown 后遇到的 markdown 文本渲染问题

2016年03月31日

Github 从 2016.5.1 开始仅支持 kramdown,如果使用了其它 markdown 解析器的话,每天都会收到 github 官方邮件,提醒更改。

Note: Starting May 1st, 2016, GitHub Pages will only support kramdown. 来源

代码高亮也出现了警告:

To fix page build warnings, you must change your highlighter value to rouge in your _config.yml file.来源

既然如此,就按照 Github 要求修改 _config.yml

markdown: kramdown
highlighter: rouge

但导致了一个问题:所有使用 ``` 标记的代码块没有被正确渲染

解决办法:

Use the GitHub-Flavored Markdown (GFM) parser / mode. Change your _config.yml settings to:

   markdown: kramdown
   kramdown:
       input: GFM
       hard_wrap: false

Refer to: How can I get backtick fenced code blocks (e.g. ```) working (with kramdown)?

但又导致了另一个问题:段落内的回车换行符没有被识别

也就是说在编辑器内输入的文本:

第1行¶
第2行¶
第3行¶

被渲染成了:

第1行 第2行 第3行

这对于你国一个喜欢把文章分成行假装是诗的程序猿来讲,就很尴尬了。

Markdown 需要敲两次回车(有至少一个空白行)才能产生一个新的段落。仅仅一个回车不会被解释为换行。如果想实现段落内换行,需要在行尾「敲两个空格然后回车」,或者在行尾加标签 <br>,但这两种方式非常不友好,违背了 markdown 引以为傲的简洁特性。

这个问题对此有讨论,支持和反对各有观点:Should the markdown renderer treat a single line break as <br>?

怎么解决这个问题呢?把 hard_wrap 设置为 true。其实这个属性默认值就是 true,只是在解决上一个问题时,Github 官网给出的答案设置为了 false,我没研究其含义,就直接复制粘贴了。

Interprets line breaks literally
Insert HTML <br/> tags inside paragraphs where the original Markdown document had newlines (by default, Markdown ignores these newlines).
Used by: GFM parser 来源

其它一些问题

Markdown 有很多渲染器,有些扩展了 markdown 的核心语法,所以一份 .md 文档由不同的渲染器可能就会得到不一样的效果。那么,替换渲染器后,这些问题就凸显出来了:

  • 表示标题的 # 必须与文字内容有 1 个空格隔开:# Heading能被正确渲染,而 #Heading 可能不会被渲染;
  • 区块引用(Blockquotes) > 上面要有 1 个空行;
  • 列表内的区块引用除了上面的 1 个空行外,还要缩进 4 个空格;
  • 代码块每行都需要缩进 4 个空格,当然可以通过一种简洁的方式: ```,但列表或者区块引用内的代码块,必须要缩进 8 个空格;

我把 Android 分类的文章挨个检查修改了,怎么讲,一个对整洁排版有追求的猿 li21。
还有,不能被一些网站的 markdown 编辑器给惯出坏毛病了。

参考:Markdown 语法说明 (简体中文版)


知识共享许可协议
li2的博客WeiYi.Li 创作,采用 知识共享 署名-非商业性使用 4.0 国际 许可协议进行许可。
© 2011-2017. All rights reserved by WeiYi.Li. Powerd by Jekyll & LinAnYa's Theme