标签 Markdown 下的文章

学习如何用 Markdown 管理章节引用、图像、表格以及更多。

这篇文章对于使用 Markdown 语法做一篇调研论文进行了一个深度体验。覆盖了如何创建和引用章节、图像(用 Markdown 和 LaTeX)和参考书目。我们也讨论了一些棘手的案例和为什么使用 LaTex 是一个正确的做法。

调研

调研论文一般包括对章节、图像、表格和参考书目的引用。Pandoc 本身并不能交叉引用这些,但是它能够利用 pandoc-crossref 过滤器来完成自动编号和章节、图像、表格的交叉引用。

让我们从重写原本以 LaTax 撰写的 一个教育调研报告的例子 开始,然后用 Markdown(和一些 LaTax)、Pandoc 和 Pandoc-crossref 重写。

添加并引用章节

要想章节被自动编号,必须使用 Markdown H1 标题编写。子章节使用 H2-H4 子标题编写(通常不需要更多级别了)。例如一个章节的标题是 “Implementation”,写作 # Implementation {#sec: implementation},然后 Pandoc 会把它转化为 3. Implementation(或者转换为相应的章节编号)。Implementation 这个标题使用了 H1 并且声明了一个 {#sec: implementation} 的标签,这是作者用于引用该章节的标签。要想引用一个章节,输入 @ 符号并跟上对应章节标签,使用方括号括起来即可: [@ sec:implementation]

在这篇论文中, 我们发现了下面这个例子:

we lack experience (consistency between TAs, [@sec:implementation]).

Pandoc 转换:

we lack experience (consistency between TAs, Section 4).

章节被自动编号(这在本文最后的 Makefile 当中说明)。要创建无编号的章节,输入章节的标题并在最后添加 {-}。例如:### Designing a game for maintainability {-} 就以标题 “Designing a game for maintainability”,创建了一个无标号的章节。

添加并引用图像

添加并引用一个图像,跟添加并引用一个章节和添加一个 Markdown 图片很相似:

![Scatterplot matrix](data/scatterplots/RScatterplotMatrix2.png){#fig:scatter-matrix}

上面这一行是告诉 Pandoc,有一个标有 Scatterplot matrix 的图像以及这张图片路径是 data/scatterplots/RScatterplotMatrix2.png{#fig:scatter-matrix} 表明了用于引用该图像的名字。

这里是从一篇论文中进行图像引用的例子:

The boxes "Enjoy", "Grade" and "Motivation" ([@fig:scatter-matrix]) ...

Pandoc 产生如下输出:

The boxes "Enjoy", "Grade" and "Motivation" (Fig. 1) ...

添加及引用参考书目

大多数调研报告都把引用放在一个 BibTeX 的数据库文件中。在这个例子中,该文件被命名为 biblio.bib,它包含了论文中所有的引用。下面是这个文件的样子:

@inproceedings{wrigstad2017mastery,
    Author =       {Wrigstad, Tobias and Castegren, Elias},
    Booktitle =    {SPLASH-E},
    Title =        {Mastery Learning-Like Teaching with Achievements},
    Year =         2017
}

@inproceedings{review-gamification-framework,
  Author =       {A. Mora and D. Riera and C. Gonzalez and J. Arnedo-Moreno},
  Publisher =    {IEEE},
  Booktitle =    {2015 7th International Conference on Games and Virtual Worlds
                  for Serious Applications (VS-Games)},
  Doi =          {10.1109/VS-GAMES.2015.7295760},
  Keywords =     {formal specification;serious games (computing);design
                  framework;formal design process;game components;game design
                  elements;gamification design frameworks;gamification-based
                  solutions;Bibliographies;Context;Design
                  methodology;Ethics;Games;Proposals},
  Month =        {Sept},
  Pages =        {1-8},
  Title =        {A Literature Review of Gamification Design Frameworks},
  Year =         2015,
  Bdsk-Url-1 =   {http://dx.doi.org/10.1109/VS-GAMES.2015.7295760}
}

...

第一行的 @inproceedings{wrigstad2017mastery, 表明了出版物 的类型(inproceedings),以及用来指向那篇论文的标签(wrigstad2017mastery)。

引用这篇题为 “Mastery Learning-Like Teaching with Achievements” 的论文, 输入:

the achievement-driven learning methodology [@wrigstad2017mastery]

Pandoc 将会输出:

the achievement- driven learning methodology [30]

这篇论文将会产生像下面这样被标号的参考书目:

引用文章的集合也很容易:只要引用使用分号 ; 分隔开被标记的参考文献就可以了。如果一个引用有两个标签 —— 例如: SEABORN201514gamification-leaderboard-benefits—— 像下面这样把它们放在一起引用:

Thus, the most important benefit is its potential to increase students' motivation
and engagement [@SEABORN201514;@gamification-leaderboard-benefits].

Pandoc 将会产生:

Thus, the most important benefit is its potential to increase students’ motivation
and engagement [26, 28]

问题案例

一个常见的问题是所需项目与页面不匹配。不匹配的部分会自动移动到它们认为合适的地方,即便这些位置并不是读者期望看到的位置。因此在图像或者表格接近于它们被提及的地方时,我们需要调节一下那些元素放置的位置,使得它们更加易于阅读。为了达到这个效果,我建议使用 figure 这个 LaTeX 环境参数,它可以让用户控制图像的位置。

我们看一个上面提到的图像的例子:

![Scatterplot matrix](data/scatterplots/RScatterplotMatrix2.png){#fig:scatter-matrix}

然后使用 LaTeX 重写:

\begin{figure}[t]
\includegraphics{data/scatterplots/RScatterplotMatrix2.png}
\caption{\label{fig:matrix}Scatterplot matrix}
\end{figure}

在 LaTeX 中,figure 环境参数中的 [t] 选项表示这张图用该位于该页的最顶部。有关更多选项,参阅 LaTex/Floats, Figures, and Captions 这篇 Wikibooks 的文章。

产生一篇论文

到目前为止,我们讲了如何添加和引用(子)章节、图像和参考书目,现在让我们重温一下如何生成一篇 PDF 格式的论文。要生成 PDF,我们将使用 Pandoc 生成一篇可以被构建成最终 PDF 的 LaTeX 文件。我们还会讨论如何以 LaTeX,使用一套自定义的模板和元信息文件生成一篇调研论文,以及如何将 LaTeX 文档编译为最终的 PDF 格式。

很多会议都提供了一个 .cls 文件或者一套论文应有样式的模板;例如,它们是否应该使用两列的格式以及其它的设计风格。在我们的例子中,会议提供了一个名为 acmart.cls 的文件。

作者通常想要在他们的论文中包含他们所属的机构,然而,这个选项并没有包含在默认的 Pandoc 的 LaTeX 模板(注意,可以通过输入 pandoc -D latex 来查看 Pandoc 模板)当中。要包含这个内容,找一个 Pandoc 默认的 LaTeX 模板,并添加一些新的内容。将这个模板像下面这样复制进一个名为 mytemplate.tex 的文件中:

pandoc -D latex > mytemplate.tex

默认的模板包含以下代码:

$if(author)$
\author{$for(author)$$author$$sep$ \and $endfor$}
$endif$
$if(institute)$
\providecommand{\institute}[1]{}
\institute{$for(institute)$$institute$$sep$ \and $endfor$}
$endif$

因为这个模板应该包含作者的联系方式和电子邮件地址,在其他一些选项之间,我们更新这个模板以添加以下内容(我们还做了一些其他的更改,但是因为文件的长度,就没有包含在此处):

latex
$for(author)$
    $if(author.name)$
        \author{$author.name$}
        $if(author.affiliation)$
            \affiliation{\institution{$author.affiliation$}}
        $endif$
        $if(author.email)$
            \email{$author.email$}
        $endif$
    $else$
        $author$
    $endif$
$endfor$

要让这些更改起作用,我们还应该有下面的文件:

  • main.md 包含调研论文
  • biblio.bib 包含参考书目数据库
  • acmart.cls 我们使用的文档的集合
  • mytemplate.tex 是我们使用的模板文件(代替默认的)

让我们添加论文的元信息到一个 meta.yaml 文件:

---
template: 'mytemplate.tex'
documentclass: acmart
classoption: sigconf
title: The impact of opt-in gamification on `\\`{=latex} students' grades in a software design course
author:
- name: Kiko Fernandez-Reyes
  affiliation: Uppsala University
  email: [email protected]
- name: Dave Clarke
  affiliation: Uppsala University
  email: [email protected]
- name: Janina Hornbach
  affiliation: Uppsala University
  email: [email protected]
bibliography: biblio.bib
abstract: |
  An achievement-driven methodology strives to give students more control over their learning with enough flexibility to engage them in deeper learning. (more stuff continues)

include-before: |
      \` ``{=latex}
      \copyrightyear{2018}
      \acmYear{2018}
      \setcopyright{acmlicensed}
      \acmConference[MODELS '18 Companion]{ACM/IEEE 21th International Conference on Model Driven Engineering Languages and Systems}{October 14--19, 2018}{Copenhagen, Denmark}
      \acmBooktitle{ACM/IEEE 21th International Conference on Model Driven Engineering Languages and Systems (MODELS '18 Companion), October 14--19, 2018, Copenhagen, Denmark}
      \acmPrice{XX.XX}
      \acmDOI{10.1145/3270112.3270118}
      \acmISBN{978-1-4503-5965-8/18/10}

      \begin{CCSXML}
      <ccs2012>
      <concept>
      <concept_id>10010405.10010489</concept_id>
      <concept_desc>Applied computing~Education</concept_desc>
      <concept_significance>500</concept_significance>
      </concept>
      </ccs2012>
      \end{CCSXML}

      \ccsdesc[500]{Applied computing~Education}

      \keywords{gamification, education, software design, UML}
      \` ``
figPrefix:
  - "Fig."
  - "Figs."
secPrefix:
  - "Section"
  - "Sections"
...

这个元信息文件使用 LaTeX 设置下列参数:

  • template 指向使用的模板(mytemplate.tex
  • documentclass 指向使用的 LaTeX 文档集合(acmart
  • classoption 是在 sigconf 的案例中,指向这个类的选项
  • title 指定论文的标题
  • author 是一个包含例如 nameaffiliationemail 的地方
  • bibliography 指向包含参考书目的文件(biblio.bib
  • abstract 包含论文的摘要
  • include-before 是这篇论文的具体内容之前应该被包含的信息;在 LaTeX 中被称为 前言。我在这里包含它去展示如何产生一篇计算机科学的论文,但是你可以选择跳过
  • figPrefix 指向如何引用文档中的图像,例如:当引用图像的 [@fig:scatter-matrix] 时应该显示什么。例如,当前的 figPrefix 在这个例子 The boxes "Enjoy", "Grade" and "Motivation" ([@fig:scatter-matrix])中,产生了这样的输出:The boxes "Enjoy", "Grade" and "Motivation" (Fig. 3)。如果这里有很多图像,目前的设置表明它应该在图像号码旁边显示 Figs.
  • secPrefix 指定如何引用文档中其他地方提到的部分(类似之前的图像和概览)

现在已经设置好了元信息,让我们来创建一个 Makefile,它会产生你想要的输出。Makefile 使用 Pandoc 产生 LaTeX 文件,pandoc-crossref 产生交叉引用,pdflatex 构建 LaTeX 为 PDF,bibtex 处理引用。

Makefile 已经展示如下:

all: paper

paper:
        @pandoc -s -F pandoc-crossref --natbib meta.yaml --template=mytemplate.tex -N \
         -f markdown -t latex+raw_tex+tex_math_dollars+citations -o main.tex main.md
        @pdflatex main.tex &> /dev/null
        @bibtex main &> /dev/null
        @pdflatex main.tex &> /dev/null
        @pdflatex main.tex &> /dev/null

clean:
        rm main.aux main.tex main.log main.bbl main.blg main.out

.PHONY: all clean paper

Pandoc 使用下面的标记:

  • -s 创建一个独立的 LaTeX 文档
  • -F pandoc-crossref 利用 pandoc-crossref 进行过滤
  • --natbibnatbib (你也可以选择 --biblatex)对参考书目进行渲染
  • --template 设置使用的模板文件
  • -N 为章节的标题编号
  • -f-t 指定从哪个格式转换到哪个格式。-t 通常包含格式和 Pandoc 使用的扩展。在这个例子中,我们标明的 raw_tex+tex_math_dollars+citations 允许在 Markdown 中使用 raw_tex LaTeX。 tex_math_dollars 让我们能够像在 LaTeX 中一样输入数学符号,citations 让我们可以使用 这个扩展

要从 LaTeX 产生 PDF,按 来自bibtex 的指导处理参考书目:

@pdflatex main.tex &> /dev/null
@bibtex main &> /dev/null
@pdflatex main.tex &> /dev/null
@pdflatex main.tex &> /dev/null

脚本用 @ 忽略输出,并且重定向标准输出和错误到 /dev/null ,因此我们在使用这些命令的可执行文件时不会看到任何的输出。

最终的结果展示如下。这篇文章的库可以在 GitHub 找到:

结论

在我看来,研究的重点是协作、思想的传播,以及在任何一个恰好存在的领域中改进现有的技术。许多计算机科学家和工程师使用 LaTeX 文档系统来写论文,它对数学提供了完美的支持。来自社会科学的研究人员似乎更喜欢 DOCX 文档。

当身处不同社区的研究人员一同写一篇论文时,他们首先应该讨论一下他们将要使用哪种格式。然而如果包含太多的数学符号,DOCX 对于工程师来说不会是最简便的选择,LaTeX 对于缺乏编程经验的研究人员来说也有一些问题。就像这篇文章中展示的,Markdown 是一门工程师和社会科学家都很轻易能够使用的语言。


via: https://opensource.com/article/18/9/pandoc-research-paper

作者:Kiko Fernandez-Reyes 选题:lujun9972 译者:dianbanjiu 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

这些简单的幻灯片创建工具可以无缝地使用 Markdown,可以让你的演示添加魅力。

假设你需要做一个 演示 presentation 。在准备的过程中,你想到“我需要写几张幻灯片”。

你可能倾向于简洁的纯文本,认为 LibreOffice Writer 这样的软件对你要做的事情而言像是杀鸡用牛刀。或者你只是遵从你内心深处的极客意识。

Markdown 格式的文件转换为优雅的演示幻灯片并不困难。下面介绍可以完成这项工作的四种工具。

Landslide

在这些工具中,Landslide 具有更高的灵活性。它是一个命令行工具,可以将 Markdown、reStructuredTextTextile) 格式的文件转换为基于 Google HTML5 幻灯片模板的 HTML 文件。

你要做的不过是编写 Markdown 格式的幻灯片源文件,打开一个终端窗口并运行 landslide 命令即可,其中命令参数为 Markdown 文件的文件名。Landslide 会生成 presentation.html,可以在任何 Web 浏览器中打开。简单吧?

但不要被简易的操作误导你。Landslide 提供了不少有用的特性,例如增加注记以及为幻灯片增加配置文件。为何要使用这些特性呢?按照 Landslide 开发者的说法,这样可以汇聚不同演示中的源文件目录并重用。

 title=

在 Landslide 演示中查看演示者注记

Marp

Marp 仍处于开发中,但值得期待。它是 “Markdown Presentation Writer” 的简写。Marp 是一个基于 Electron) 的工具,让你在一个简单的双栏编辑器中编写幻灯片:在左栏编写 Markdown,在右栏中预览效果。

Marp 支持 GitHub 风格 Markdown。如果你需要一个使用 GitHub 风格 Markdown 编写幻灯片的快速教程,可以参考 示例项目。GitHub 风格 Markdown 比基础 Markdown 更加灵活。

Marp 只自带两个基础主题,但你可以为幻灯片增加背景图片、调整图片大小以及增加数学表达式。不足之处,目前只支持 PDF 格式导出。老实说,我很好奇为何不一开始就提供 HTML 格式导出。

 title=

使用 Marp 编辑简单的幻灯片

Pandoc

你可能已经知道 pandoc 是一种支持多种 标记语言 markup languages 相互转换的神奇工具。但你可能不知道,pandoc 可以将 Markdown 格式文件转换为 Slidy)、SlideousDZSlidesReveal.js 等演示框架支持的优雅 HTML 幻灯片。如果你使用 LaTeX,可以使用 Beamer 软件包)输出 PDF 格式的幻灯片。

你需要在幻灯片中使用特定格式,但可以通过变量控制其效果。你也可以更改幻灯片的外观与风格,增加幻灯片之间的暂停,添加演示者注记等。

当然,你需要在你的主机上安装你喜欢的演示框架,因为 Pandoc 只生成原始幻灯片文件。

 title=

查看使用 Pandoc 和 DZSlides 创建的幻灯片

Hacker Slides

Hacker Slides 是一个 SandstormSandstorm Oasis 平台上的应用,基于 Markdown 和 Reveal.js 幻灯片框架。生成的幻灯片可以比较朴素,也可以很炫。

在浏览器的两栏界面中编写幻灯片,左栏输入 Markdown 文本,右栏渲染效果。当你制作完成后,可以在 Sandstorm 中演示,也可以生成分享链接让其它人演示。

你可能会说,你不使用 Sandstorm 或 Sandstorm Oasis 怎么办?不要担心,Hacker Slides 提供了可以在桌面或服务器上运行的版本

 title=

在 Hacker Slides 中编辑幻灯片

两点特别补充

如果你使用 Jupyter 笔记本 Notebooks (参考社区版主 Don Watkins 的文章)发布数据或指令文本,你可以使用 Jupyter2slides。该工具基于 Reveal.js,可以将笔记本转换为一系列精美的 HTML 幻灯片。

如果你倾向于托管应用,试试 GitPitch,支持 GitHub、GitLab 和 Bitbucket。只需在将幻灯片源文件推送到支持的代码仓库中,在 GitPitch 中指向该仓库,这样你就可以在 GitPitch 网站上看到你的幻灯片了。

你有最喜欢的基于 Markdown 的幻灯片生成器吗?留下评论分享吧。


via: https://opensource.com/article/18/5/markdown-slide-generators

作者:Scott Nesbitt 选题:lujun9972 译者:pinewall 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

Markdown

首先,对 Markdown 进行一个简单的介绍。Markdown 是由 John Gruber 和 Aaron Swartz 共同创建的一种轻量级纯文本格式语法。Markdown 可以让用户“以易读、易写的纯文本格式来进行写作,然后可以将其转换为有效格式的 XHTML(或 HTML)“。Markdown 语法只包含一些非常容易记住的符号。其学习曲线平缓;你可以在炒蘑菇的同时一点点学习 Markdown 语法(大约 10 分钟)。通过使用尽可能简单的语法,错误率达到了最小化。除了拥有友好的语法,它还具有直接输出干净、有效的(X)HTML 文件的强大功能。如果你看过我的 HTML 文件,你就会知道这个功能是多么的重要。

Markdown 格式语法的主要目标是实现最大的可读性。用户能够以纯文本的形式发布一份 Markdown 格式的文件。用 Markdown 进行文本写作的一个优点是易于在计算机、智能手机和个人之间共享。几乎所有的内容管理系统都支持 Markdown 。它作为一种网络写作格式流行起来,其产生一些被许多服务采用的变种,比如 GitHub 和 Stack Exchange 。

你可以使用任何文本编辑器来写 Markdown 文件。但我建议使用一个专门为这种语法设计的编辑器。这篇文章中所讨论的软件允许你使用 Markdown 语法来写各种格式的专业文档,包括博客文章、演示文稿、报告、电子邮件以及幻灯片等。另外,所有的应用都是在开源许可证下发布的,在 Linux、OS X 和 Windows 操作系统下均可用。

Remarkable

让我们从 Remarkable 开始。Remarkable 是一个 apt 软件包的名字,它是一个相当有特色的 Markdown 编辑器 — 它并不支持 Markdown 的全部功能特性,但该有的功能特性都有。它使用和 GitHub Markdown 类似的语法。

你可以使用 Remarkable 来写 Markdown 文档,并在实时预览窗口查看更改。你可以把你的文件导出为 PDF 格式(带有目录)和 HTML 格式文件。它有强大的配置选项,从而具有许多样式,因此,你可以把它配置成你最满意的 Markdown 编辑器。

其他一些特性:

在 Debian、Ubuntu、Fedora、SUSE 和 Arch 系统上均有 Remarkable 的可用的简易安装程序。

主页: https://remarkableapp.github.io/ 许可证: MIT 许可

Atom

毫无疑问, Atom 是一个神话般的文本编辑器。超过 50 个开源包集合在一个微小的内核上,从而构成 Atom 。伴有 Node.js 的支持,以及全套功能特性,Atom 是我最喜欢用来写代码的编辑器。Atom 的特性在杀手级开源应用的文章中有更详细介绍,它是如此的强大。但是作为一个 Markdown 编辑器,Atom 还有许多不足之处,它的默认包不支持 Markdown 的特性。例如,正如上图所展示的,它不支持等价渲染。

但是,开源拥有强大的力量,这是我强烈提倡开源的一个重要原因。Atom 上有许多包以及一些复刻,从而添加了缺失的功能特性。比如,Markdown Preview Plus 提供了 Markdown 文件的实时预览,并伴有数学公式渲染和实时重加载。另外,你也可以尝试一下 Markdown Preview Enhanced。如果你需要自动滚动特性,那么 markdown-scroll-sync 可以满足你的需求。我是 Markdown-WriterMarkdown-pdf的忠实拥趸,后者支持将 Markdown 快速转换为 PDF、PNG 以及 JPEG 文件。

这个方式体现了开源的理念:允许用户通过添加扩展来提供所需的特性。这让我想起了 Woolworths 的 n 种杂拌糖果的故事。虽然需要多付出一些努力,但能收获最好的回报。

主页: https://atom.io/ 许可证: MIT 许可

Haroopad

Haroopad 是一个优秀的 Markdown 编辑器,是一个用于创建适宜 Web 的文档的处理器。使用 Haroopad 可以创作各种格式的文档,比如博客文章、幻灯片、演示文稿、报告和电子邮件等。Haroopad 在 Windows、Mac OS X 和 Linux 上均可用。它有 Debian/Ubuntu 的软件包,也有 Windows 和 Mac 的二进制文件。该应用程序使用 node-webkit、CodeMirror,marked,以及 Twitter 的 Bootstrap 。

Haroo 在韩语中的意思是“一天”。

它的功能列表非常可观。请看下面:

  • 主题、皮肤和 UI 组件

    • 超过 30 种不同的编辑主题 - tomorrow-night-bright 和 zenburn 是近期刚添加的
    • 编辑器中的代码块的语法高亮
    • Ruby、Python、PHP、Javascript、C、HTML 和 CSS 的语法高亮支持
    • 基于 CodeMirror,这是一个在浏览器中使用 JavaScript 实现的通用文本编辑器
  • 实时预览主题

    • 基于 markdown-css 的 7 个主题
  • 语法高亮

    • 基于 hightlight.js 的 112 种语言以及 49 种样式
  • 定制主题

    • 基于 CSS (层叠样式表)的样式
  • 演示模式 - 对于现场演示非常有用
  • 绘图 - 流程图和序列图
  • 任务列表
  • 扩展 Markdown 语法,支持 TOC(目录)、 GitHub 风味 Markdown 以及数学表达式、脚注和任务列表等
  • 字体大小

    • 使用首选窗口和快捷键来设置编辑器和预览字体大小
  • 嵌入富媒体内容

    • 视频、音频、3D、文本、开放图形以及 oEmbed
    • 支持大约 100 种主要的网络服务(YouTude、SoundCloud、Flickr 等)
    • 支持拖放
  • 显示模式

    • 默认:编辑器|预览器,倒置:预览器|编辑器,仅编辑器,仅预览器(View -> Mode)
  • 插入当前日期和时间

    • 多种格式支持(Insert -> Data & Time)
  • HtML 到 Markdown

    • 拖放你在 Web 浏览器中选择好的文本
  • Markdown 解析选项
  • 大纲预览
  • 纯粹主义者的 Vim 键位绑定
  • Markdown 自动补全
  • 导出为 PDF 和 HTML
  • 带有样式的 HTML 复制到剪切板可用于所见即所得编辑器
  • 自动保存和恢复
  • 文件状态信息
  • 换行符或空格缩进
  • (一、二、三)列布局视图
  • Markdown 语法帮助对话框
  • 导入和导出设置
  • 通过 MathJax 支持 LaTex 数学表达式
  • 导出文件为 HTML 和 PDF
  • 创建扩展来构建自己的功能
  • 高效地将文件转换进博客系统:WordPress、Evernote 和 Tumblr 等
  • 全屏模式-尽管该模式不能隐藏顶部菜单栏和顶部工具栏
  • 国际化支持:英文、韩文、西班牙文、简体中文、德文、越南文、俄文、希腊文、葡萄牙文、日文、意大利文、印度尼西亚文土耳其文和法文

主页 http://pad.haroopress.com/ 许可证: GNU GPL v3 许可

StackEdit

StackEdit 是一个功能齐全的 Markdown 编辑器,基于 PageDown(该 Markdown 库被 Stack Overflow 和其他一些 Stack 交流网站使用)。不同于在这个列表中的其他编辑器,StackEdit 是一个基于 Web 的编辑器。在 Chrome 浏览器上即可使用 StackEdit 。

特性包括:

  • 实时预览 HTML,并通过绑定滚动连接特性来将编辑器和预览的滚动条相绑定
  • 支持 Markdown Extra 和 GitHub 风味 Markdown,Prettify/Highlight.js 语法高亮
  • 通过 MathJax 支持 LaTex 数学表达式
  • 所见即所得的控制按键
  • 布局配置
  • 不同风格的主题支持
  • la carte 扩展
  • 离线编辑
  • 可以与 Google 云端硬盘(多帐户)和 Dropbox 在线同步
  • 一键发布到 Blogger、Dropbox、Gist、GitHub、Google Drive、SSH 服务器、Tumblr 和 WordPress

主页: https://stackedit.io/ 许可证: Apache 许可

MacDown

MacDown 是在这个列表中唯一一个只运行在 macOS 上的全特性编辑器。具体来说,它需要在 OX S 10.8 或更高的版本上才能使用。它在内部使用 Hoedown 将 Markdown 渲染成 HTML,这使得它的特性更加强大。Heodown 是 Sundown 的一个复活复刻。它完全符合标准,无依赖,具有良好的扩展支持和 UTF-8 感知。

MacDown 基于 Mou,这是专为 Web 开发人员设计的专用解决方案。

它提供了良好的 Markdown 渲染,通过 Prism 提供的语言识别渲染实现代码块级的语法高亮,MathML 和 LaTex 渲染,GTM 任务列表,Jekyll 前端以及可选的高级自动补全。更重要的是,它占用资源很少。想在 OS X 上写 Markdown?MacDown 是我针对 Web 开发者的开源推荐。

主页: https://macdown.uranusjr.com/ 许可证: MIT 许可

ghostwriter

ghostwriter 是一个跨平台的、具有美感的、无干扰的 Markdown 编辑器。它内建了 Sundown 处理器支持,还可以自动检测 pandoc、MultiMarkdown、Discount 和 cmark 处理器。它试图成为一个朴实的编辑器。

ghostwriter 有许多很好的功能设置,包括语法高亮、全屏模式、聚焦模式、主题、通过 Hunspell 进行拼写检查、实时字数统计、实时 HTML 预览、HTML 预览自定义 CSS 样式表、图片拖放支持以及国际化支持。Hemingway 模式按钮可以禁用退格键和删除键。一个新的 “Markdown cheat sheet” HUD 窗口是一个有用的新增功能。主题支持很基本,但在 GitHub 仓库上也有一些可用的试验性主题。

ghostwriter 的功能有限。我越来越欣赏这个应用的通用性,部分原因是其简洁的界面能够让写作者完全集中在策划内容上。这一应用非常值得推荐。

ghostwirter 在 Linux 和 Windows 系统上均可用。在 Windows 系统上还有一个便携式的版本可用。

主页: https://github.com/wereturtle/ghostwriter 许可证: GNU GPL v3 许可

Abricotine

Abricotine 是一个为桌面构建的、旨在跨平台且开源的 Markdown 编辑器。它在 Linux、OS X 和 Windows 上均可用。

该应用支持 Markdown 语法以及一些 GitHub 风味的 Markdown 增强(比如表格)。它允许用户直接在文本编辑器中预览文档,而不是在侧窗栏。

该应用有一系列有用的特性,包括拼写检查、以 HTML 格式保存文件或把富文本复制粘贴到邮件客户端。你也可以在侧窗中显示文档目录,展示语法高亮代码、以及助手、锚点和隐藏字符等。它目前正处于早期的开发阶段,因此还有一些很基本的 bug 需要修复,但它值得关注。它有两个主题可用,如果有能力,你也可以添加你自己的主题。

主页: http://abricotine.brrd.fr/ 许可证: GNU 通用公共许可证 v3 或更高许可

ReText

ReText 是一个简单而强大的 Markdown 和 reStructureText 文本编辑器。用户可以控制所有输出的格式。它编辑的文件是纯文本文件,但可以导出为 PDF、HTML 和其他格式的文件。ReText 官方仅支持 Linux 系统。

特性包括:

  • 全屏模式
  • 实时预览
  • 同步滚动(针对 Markdown)
  • 支持数学公式
  • 拼写检查
  • 分页符
  • 导出为 HTML、ODT 和 PDF 格式
  • 使用其他标记语言

主页: https://github.com/retext-project/retext 许可证: GNU GPL v2 或更高许可


via: https://www.ossblog.org/markdown-editors/

作者:Steve Emms 译者:ucasFL 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

很庆幸,我们当初选择 Markdown 作为用户在 GitHub 上托管内容的标记语言,它为用户提供了强大且直接的方式 (不管是技术的还是非技术的) 来编写可以很好的渲染成 HTML 的纯文本文档。

然而,其最主要的限制,就是缺乏在最模糊的语言细节上的标准。比如,使用多少个空格来进行行缩进、两个不同元素之间需要使用多少空行区分、大量繁琐细节往往造成不同的实现:相似的 Markdown 文档会因为选用的不同的语法解析器而渲染成相当不同的呈现效果。

五年前,我们在 Sundown 的基础之上开始构建 GitHub 自定义版本的 Markdown —— GFM ( GitHub 风格的 Markdown GitHub Flavored Markdown ),这是我们特地为解决当时已有的 Markdown 解析器的不足而开发的一款解析器。

今天,我们希望通过发布 GitHub 风格的 Markdown 的正式语法规范及其相应的参考实现来改善现状。

该正式规范基于 CommonMark,这是一个雄心勃勃的项目,旨在通过一个反映现实世界用法的方式来规范目前互联网上绝大多数网站使用的 Markdown 语法。CommonMark 允许人们以他们原有的习惯来使用 Markdown,同时为开发者提供一个综合规范和参考实例,从而实现跨平台的 Markdown 互操作和显示。

规范

使用 CommonMark 规范并围绕它来重新加工我们当前用户内容需要不少努力。我们纠结的主要问题是该规范 (及其参考实现) 过多关注由原生 Perl 实现支持的 Markdown 通用子集。这还不包括那些 GitHub 上已经在用的扩展特性。最明显的就是缺少 表格 tables 删除线 strikethrough 自动链接 autolinks 任务列表 task lists 的支持。

为完全描述 GitHub 的 Markdown 版本 (也称为 GFM),我们必须要要正式定义这些特性的的语法和语意,这在以前从未做过。我们是在现存的 CommonMark 规范中来完成这一项工作的,同时还特意关注以确保我们的扩展是原有规范的一个严格且可选的超集。

当评估 GFM 规范 的时候,你可以清楚的知道哪些是 GFM 特定规范的补充内容,因为它们都高亮显示了。并且你也会看到原有规范的所有部分都保持原样,因此,GFM 规范能够与任何其他的实现保持兼容。

实现

为确保我们网站中的 Markdown 渲染能够完美兼容 CommonMark 规范,GitHub 的 GFM 解析器的后端实现基于 cmark 来开发,这是 CommonMark 规范的一个参考实现,由 John MacFarlane 和许多其他的 出色的贡献者 开发完成。

就像规范本身那样,cmark 是 Markdown 的严格子集解析器,所以我们还必须在现存解析器的基础上完成 GitHub 自定义扩展的解析功能。你可以通过 cmark 的分支 来查看变更记录;为了跟踪不断改进的上游项目,我们持续将我们的补丁变基到上游主线上去。我们希望,这些扩展的正式规范一旦确定,这些补丁集同样可以应用到原始项目的上游变更中去。

除了在 cmark 分支中实现 GFM 规范特性,我们也同时将许多目标相似的变更贡献到上游。绝大多数的贡献都主要围绕性能和安全。我们的后端每天都需要渲染大量的 Markdown 文档,所以我们主要关注这些操作可以尽可能的高效率完成,同时还要确保那些滥用的恶意 Markdown 文档无法攻击到我们的服务器。

第一版使用 C 语言编写的解析器存在严重的安全隐患:通过足够深度的特殊 Markdown 元素的嵌套,它可能造成堆栈溢出 (甚至有时候可以运行任意代码)。而 cmark 实现,就像我们之前设计的解析器 Sundown,从一开始设计就考虑到要抵御这些攻击。其解析算法和基于 AST 的输出可以优雅的解决深层递归以及其他的恶意文档格式。

cmark 在性能方面则是有点粗糙:基于实现 Sundown 时我们所学到的性能技巧,我们向上游贡献了许多优化方案,但除去所有这些变更之外,当前版本的 cmark 仍然无法与 Sundown 本身匹敌:我们的基准测试表明,cmark 在绝大多数文档渲染的性能上要比 Sundown 低 20% 到 30%。

那句古老的优化谚语 最快的代码就是不需要运行的代码 the fastest code is the code that doesn’t run 在此处同样适用:实际上,cmark 比 Sundown 要多进行一些操作。在其他的功能上,cmark 支持 UTF8 字符集,对参考的支持、扩展的接口清理的效果更佳。最重要的是它如同 Sundown 那样,并不会将 Markdown 翻译成 HTML。它实际上从 Markdown 源码中生成一个 AST (抽象语法树,Abstract Syntax Tree),然后我们就看将之转换和逐渐渲染成 HTML。

如果考虑下我们在 Sundown 的最初实现 (特别是文档中关于查询用户的 mention 和 issue 引用、插入任务列表等) 时的 HTML 语法剖析工作量,你会发现 cmark 基于 AST 的方法可以节约大量时间 降低我们用户内容堆栈的复杂度。Markdown AST 是一个非常强大的工具,并且值得 cmark 生成它所付出的性能成本。

迁移

变更我们用户的内容堆栈以兼容 CommonMark 规范,并不同于转换我们用来解析 Markdown 的库那样容易:目前我们在遇到最根本的障碍就是由于一些不常用语法 (LCTT 译注:原文是 the Corner,作为名词的原意为角落、偏僻处、窘境,这应该是指那些不常用语法),CommonMark 规范 (以及有歧义的 Markdown 原文) 可能会以一种意想不到的方式来渲染一些老旧的 Markdown 内容。

通过综合分析 GitHub 中大量的 Markdown 语料库,我们断定现存的用户内容只有不到 1% 会受到新版本实现的影响:我们是通过同时使用新 (cmark,兼容 CommonMark 规范) 旧 (Sundown) 版本的库来渲染大量的 Markdown 文档、标准化 HTML 结果、分析它们的不同点,最后才得到这一个数据的。

只有 1% 的文档存在少量的渲染问题,使得换用新实现并获取其更多出看起来是非常合理的权衡,但是是根据当前 GitHub 的规模,这个 1% 是非常多的内容以及很多的受影响用户。我们真的不想导致任何用户需要重新校对一个老旧的问题、看到先前可以渲染成 HTML 的内容又呈现为 ASCII 码 —— 尽管这明显不会导致任何原始内容的丢失,却是糟糕的用户体验。

因此,我们想出相应的方法来缓和迁移过程。首先,第一件我们做的事就是收集用户托管在我们网站上的两种不同类型 Markdown 的数据:用户的评论 (比如 Gist、issue、PR 等)以及在 git 仓库中的 Markdown 文档。

这两种内容有着本质上的区别:用户评论存储在我们的数据库中,这意味着他们的 Markdown 语法可以标准化 (比如添加或移除空格、修正缩进或则插入缺失的 Markdown 说明符,直到它们可正常渲染为止)。然而,那些存储在 Git 仓库中的 Markdown 文档则是 根本 无法触及,因为这些内容已经散列成为 Git 存储模型的一部分。

幸运的是,我们发现绝大多数使用了复杂的 Markdown 特性的用户内容都是用户评论 (特别是 issue 主体和 PR 主体),而存储于仓库中的文档则大多数情况下都可以使用新的和旧的渲染器正常进行渲染。

因此,我们加快了标准化现存用户内容的语法的进程,以便使它们在新旧实现下渲染效果一致。

我们用以文档转换的方法相当实用:我们那个旧的 Markdown 解析器, Sundown,更多的是扮演着翻译器而非解析器的角色。输入 Markdown 内容之后,一系列的语意回调就会把原始的 Markdown 内容转换为目标语言 (在我们的实际使用中是 HTML5) 的对应标记。基于这一设计方法,我们决定使用语意回调让 Sumdown 将原始 Markdown 转换为兼容 CommonMark 的 Markdown,而非 HTML。

除了转换之外,这还是一个高效的标准化过程,并且我们对此信心满满,毕竟完成这一任务的是我们在五年前就使用过的解析器。因此,所有的现存文档在保留其原始语意的情况下都能够进行明确的解析。

一旦升级 Sundown 来标准化输入文档并充分测试之后,我们就会做好开启转换进程的准备。最开始的一步,就是对所有新用户内容切换到新的 cmark 实现上,以便确保我们能有一个有限的分界点来进行过渡。实际上,几个月前我们就为网站上所有 新的 用户评论启用了 CommonMark,这一过程几乎没有引起任何人注意 —— 这是关于 CommonMark 团队出色工作的证明,通过一个最具现实世界用法的方式来正式规范 Markdown 语言。

在后端,我们开启 MySQL 转换来升级替代所有 Markdown 用户内容。在所有的评论进行标准化之后,在将其写回到数据库之前,我们将使用新实现来进行渲染并与旧实现的渲染结果进行对比,以确保 HTML 输出结果视觉上感觉相同,并且用户数据在任何情况下都不会被破坏。总而言之,只有不到 1% 的输入文档会受到标准进程的修改,这符合我们的的期望,同时再次证明 CommonMark 规范能够呈现语言的真实用法。

整个过程会持续好几天,最后的结果是网站上所有的 Markdown 用户内容会得到全面升级以符合新的 Markdown 标准,同时确保所有的最终渲染输出效果对用户视觉上感觉相同。

结论

从今天 (LCTT 译注:原文发布于 2017 年 3 月 14 日,这里的今天应该是这个日期) 开始, 我们同样为所有存储在 Git 仓库中的 Markdown 内容启动 CommonMark 渲染。正如上文所述,所有的现存文档都不会进行标准化,因为我们所期望中的多数渲染效果都刚刚好。

能够让在 GitHub 上的所有 Markdown 内容符合一个动态变化且使用的标准,同时还可以为我的用户提供一个关于 GFM 如何进行解析和渲染 清晰且权威的参考说明,我们是相当激动的。

我们还将致力于 CommonMark 规范,一直到在它正式发布之前消除最后一个 bug。我们也希望 GitHub.com 在其 1.0 规范发布之后可以进行完美兼容。

作为结束,以下为想要学习 CommonMark 规范或则自己来编写实现的朋友提供一些有用的链接。


译者简介:

GHLandy —— 生活中所有欢乐与苦闷都应藏在心中,有些事儿注定无人知晓,自己也无从说起。


via: https://githubengineering.com/a-formal-spec-for-github-markdown/

作者:Yuki IzumiVicent Martí 译者:GHLandy 校对:jasminepeng

本文由 LCTT 原创编译,Linux中国 荣誉推出

Markdown 是一种简单的标记语言,旨在帮助你花费更小的代价来格式化纯文本文档。在 WordPress 下你可以使用 HTML 或者可视化编辑器来格式化你的文档,但是使用 markdown 可以让格式化文档变得更加容易,而且你随时可以导出成很多种格式,包括(但不限于)HTML。

WordPress 没有原生的 markdown 的支持,但是,如果你希望的话,在你的网站上有多种插件可以添加这种功能。

在这个教程中,我将会演示如何使用流行的 WP-Markdown 插件为 WordPress 网站添加 markdown 支持。

安装

导航到 “Plugins -> Add New”,然后在提供的搜索框中输入 “wp-markdown” 就可以直接安装。插件应该会出现在列表中的第一个。单击 “Install Now” 进行安装。

配置

当你已经安装了这个插件并且激活它之后,导航到 “Settings -> Writing” 并向下滚动,直到 markdown 选项。

你可以启用文章、页面和评论中对于 markdown 的支持。如果你刚刚开始学习 markdown 语法的话,那么你也可以在文章编辑器或者评论的地方启用一个帮助栏,这可以使你更方便一些。

如果在你的博客文章中包括代码片段的话,那么启用 “Prettify syntax highlighter” 将会让你的代码片段自动语法高亮。

一旦对于你的选择感觉满意的话,那么就单击 “Save Changes” 来保存你的设置吧。

使用 Markdown 来写你的文章

当你在自己网站中启用了 markdown 的支持,你就可以立马开始使用了。

通过 “Posts -> Add New” 创建一篇新的文章。你将会注意到默认的可视化及纯文本编辑器已经被 markdown 编辑器所替代。

如果你在配置选项中没有启用 markdown 的帮助栏,你将不会看到 markdown 格式化后的实时预览。然而,只要你的语法是正确的,当你保存或者发布文章的时候,你的 markdown 就会转换成正确的 HTML。

然而,如果你是 markdown 的初学者的话,实时预览这一特征对你会很重要,只需要简单的回到刚才的设置中启用帮助栏选项,你就可以在你的文章底部看到一块漂亮的实时预览区域。另外,你也可以在顶部看到很多按钮,它们将帮助你在文章中快速的插入 markdown 格式。

结语

正如你所看到的那样,在 WordPress 网站上添加 markdown 支持确实容易,你将只需要花费几分钟的时间就可以了。如果对于 markdown 你全然不知的话,或许你也可以查看我们的 markdown 备忘录,它将对于 markdown 语法提供一个全面的参考。


via: https://www.maketecheasier.com/use-markdown-in-wordpress/

作者:Ayo Isaiah 译者:yangmingming 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出

在这篇文章中,我们会点评一些可以在 Linux 上安装使用的最好的 Markdown 编辑器。 你可以在 Linux 平台上找到非常多的 的 Markdown 编辑器,但是在这里我们将尽可能地为您推荐那些最好的。

Best Linux Markdown Editors

对于不了解 Markdown 的人做个简单介绍,Markdown 是由著名的 Aaron Swartz 和 John Gruber 发明的标记语言,其最初的解析器是一个用 Perl 写的简单、轻量的同名工具。它可以将用户写的纯文本转为可用的 HTML(或 XHTML)。它实际上是一门易读,易写的纯文本语言,以及一个用于将文本转为 HTML 的转换工具。

希望你先对 Markdown 有一个稍微的了解,接下来让我们逐一列出这些编辑器。

1. Atom

Atom 是一个现代的、跨平台、开源且强大的文本编辑器,它可以运行在 Linux、Windows 和 MAC OS X 等操作系统上。用户可以在它的基础上进行定制,删减修改任何配置文件。

它包含了一些非常杰出的特性:

  • 内置软件包管理器
  • 智能自动补全功能
  • 提供多窗口操作
  • 支持查找替换功能
  • 包含一个文件系统浏览器
  • 轻松自定义主题
  • 开源、高度扩展性的软件包等

Atom Markdown Editor for Linux

访问主页: https://atom.io/

2. GNU Emacs

Emacs 是 Linux 平台上一款的流行文本编辑器。它是一个非常棒的、具备高扩展性和定制性的 Markdown 语言编辑器。

它综合了以下这些神奇的特性:

  • 带有丰富的内置文档,包括适合初学者的教程
  • 有完整的 Unicode 支持,可显示所有的人类符号
  • 支持内容识别的文本编辑模式
  • 包括多种文件类型的语法高亮
  • 可用 Emacs Lisp 或 GUI 对其进行高度定制
  • 提供了一个包系统可用来下载安装各种扩展等

Emacs Markdown Editor for Linux

访问主页: https://www.gnu.org/software/emacs/

3. Remarkable

Remarkable 可能是 Linux 上最好的 Markdown 编辑器了,它也适用于 Windows 操作系统。它的确是是一个卓越且功能齐全的 Markdown 编辑器,为用户提供了一些令人激动的特性。

一些卓越的特性:

  • 支持实时预览
  • 支持导出 PDF 和 HTML
  • 支持 Github Markdown 语法
  • 支持定制 CSS
  • 支持语法高亮
  • 提供键盘快捷键
  • 高可定制性和其他

Remarkable Markdown Editor for Linux

访问主页: https://remarkableapp.github.io

4. Haroopad

Haroopad 是为 Linux,Windows 和 Mac OS X 构建的跨平台 Markdown 文档处理程序。用户可以用它来书写许多专家级格式的文档,包括电子邮件、报告、博客、演示文稿和博客文章等等。

功能齐全且具备以下的亮点:

  • 轻松导入内容
  • 支持导出多种格式
  • 广泛支持博客和邮件
  • 支持许多数学表达式
  • 支持 Github Markdown 扩展
  • 为用户提供了一些令人兴奋的主题、皮肤和 UI 组件等等

Haroopad Markdown Editor for Linux

访问主页: http://pad.haroopress.com/

5. ReText

ReText 是为 Linux 和其它几个 POSIX 兼容操作系统提供的简单、轻量、强大的 Markdown 编辑器。它还可以作为一个 reStructuredText 编辑器,并且具有以下的特性:

  • 简单直观的 GUI
  • 具备高定制性,用户可以自定义语法文件和配置选项
  • 支持多种配色方案
  • 支持使用多种数学公式
  • 启用导出扩展等等

ReText Markdown Editor for Linux

访问主页: https://github.com/retext-project/retext

6. UberWriter

UberWriter 是一个简单、易用的 Linux Markdown 编辑器。它的开发受 Mac OS X 上的 iA writer 影响很大,同样它也具备这些卓越的特性:

  • 使用 pandoc 进行所有的文本到 HTML 的转换
  • 提供了一个简洁的 UI 界面
  • 提供了一种 专心 distraction free 模式,高亮用户最后的句子
  • 支持拼写检查
  • 支持全屏模式
  • 支持用 pandoc 导出 PDF、HTML 和 RTF
  • 启用语法高亮和数学函数等等

UberWriter Markdown Editor for Linux

访问主页: http://uberwriter.wolfvollprecht.de/

7. Mark My Words

Mark My Words 同样也是一个轻量、强大的 Markdown 编辑器。它是一个相对比较新的编辑器,因此提供了包含语法高亮在内的大量的功能,简单和直观的 UI。

下面是一些棒极了,但还未捆绑到应用中的功能:

  • 实时预览
  • Markdown 解析和文件 IO
  • 状态管理
  • 支持导出 PDF 和 HTML
  • 监测文件的修改
  • 支持首选项设置

MarkMyWords Markdown Editor for-Linux

访问主页: https://github.com/voldyman/MarkMyWords

8. Vim-Instant-Markdown 插件

Vim 是 Linux 上的一个久经考验的强大、流行而开源的文本编辑器。它用于编程极棒。它也高度支持插件功能,可以让用户为其增加一些其它功能,包括 Markdown 预览。

有好几种 Vim 的 Markdown 预览插件,但是 Vim-Instant-Markdown 的表现最佳。

9. Bracket-MarkdownPreview 插件

Brackets 是一个现代、轻量、开源且跨平台的文本编辑器。它特别为 Web 设计和开发而构建。它的一些重要功能包括:支持内联编辑器、实时预览、预处理支持及更多。

它也是通过插件高度可扩展的,你可以使用 Bracket-MarkdownPreview 插件来编写和预览 Markdown 文档。

Brackets Markdown Plugin Preview

10. SublimeText-Markdown 插件

Sublime Text 是一个精心打造的、流行的、跨平台文本编辑器,用于代码、markdown 和普通文本。它的表现极佳,包括如下令人兴奋的功能:

  • 简洁而美观的 GUI
  • 支持多重选择
  • 提供专心模式
  • 支持窗体分割编辑
  • 通过 Python 插件 API 支持高度插件化
  • 完全可定制化,提供命令查找模式

SublimeText-Markdown 插件是一个支持格式高亮的软件包,带有一些漂亮的颜色方案。

SublimeText Markdown Plugin Preview

结论

通过上面的列表,你大概已经知道要为你的 Linux 桌面下载、安装什么样的 Markdown 编辑器和文档处理程序了。

请注意,这里提到的最好的 Markdown 编辑器可能对你来说并不是最好的选择。因此你可以通过下面的反馈部分,为我们展示你认为列表中未提及的,并且具备足够的资格的,令人兴奋的 Markdown 编辑器。


via: http://www.tecmint.com/best-markdown-editors-for-linux/

作者:Aaron Kili 译者:Locez 校对:wxy

本文由 LCTT 原创编译,Linux中国 荣誉推出