标签 Markdown 下的文章

生活在普通文本世界么?以下是无需使用文字处理器而创建别人要的格式化文档的方法。

如果你生活在普通文本世界里,总会有人要求你提供格式化文档。我就经常遇到这个问题,特别是在 Day JobTM。虽然我已经给与我合作的开发团队之一介绍了用于撰写和审阅发行说明的 Docs Like Code 工作流程,但是还有少数人对 GitHub 和使用 Markdown 没有兴趣,他们更喜欢为特定的专有应用格式化的文档。

好消息是,你不会被卡在将未格式化的文本复制粘贴到文字处理器的问题当中。使用 pandoc,你可以快速地给人们他们想要的东西。让我们看看如何使用 pandoc 将文档从 Markdown 转换为 Linux 中的文字处理器格式。

请注意,pandoc 也可用于从两种 BSD(NetBSDFreeBSD)到 Chrome OS、MacOS 和 Windows 等的各种操作系统。

基本转换

首先,在你的计算机上安装 pandoc。然后,打开控制台终端窗口,并导航到包含要转换的文件的目录。

输入此命令以创建 ODT 文件(可以使用 LibreOffice WriterAbiWord 等字处理器打开):

pandoc -t odt filename.md -o filename.odt

记得用实际文件名称替换 filename。如果你需要为其他文字处理器(你知道我的意思)创建一个文件,替换命令行的 odtdocx。以下是本文转换为 ODT 文件时的内容:

 title=

这些转换结果虽然可用,但有点乏味。让我们看看如何为转换后的文档添加更多样式。

带样式转换

pandoc 有一个漂亮的功能,使你可以在将带标记的纯文本文件转换为字处理器格式时指定样式模板。在此文件中,你可以编辑文档中的少量样式,包括控制段落、文章标题和副标题、段落标题、说明、基本的表格和超链接的样式。

让我们来看看能做什么。

创建模板

要设置文档样式,你不能只是使用任何一个模板就行。你需要生成 pandoc 称之为引用模板的文件,这是将文本文件转换为文字处理器文档时使用的模板。要创建此文件,请在终端窗口中键入以下内容:

pandoc -o custom-reference.odt --print-default-data-file reference.odt

此命令创建一个名为 custom-reference.odt 的文件。如果你正在使用其他文字处理程序,请将命令行中的 “odt” 更改为 “docx”。

在 LibreOffice Writer 中打开模板文件,然后按 F11 打开 LibreOffice Writer 的 “样式” 窗格。虽然 pandoc 手册建议不要对该文件进行其他更改,但我会在必要时更改页面大小并添加页眉和页脚。

使用模板

那么,你要如何使用刚刚创建的模板?有两种方法可以做到这一点。

最简单的方法是将模板放在家目录的 .pandoc 文件夹中,如果该文件夹不存在,则必须先创建该文件夹。当转换文档时,pandoc 会使用此模板文件。如果你需要多个模板,请参阅下一节了解如何从多个模板中进行选择。

使用模板的另一种方法是在命令行键入以下转换选项:

pandoc -t odt file-name.md --reference-doc=path-to-your-file/reference.odt -o file-name.odt

如果你想知道使用自定义模板转换后的文件是什么样的,这是一个示例:

 title=

选择模板

很多人只需要一个 pandoc 模板,但是,有些人需要不止一个。

例如,在我的日常工作中,我使用了几个模板:一个带有 DRAFT 水印,一个带有表示内部使用的水印,另一个用于文档的最终版本。每种类型的文档都需要不同的模板。

如果你有类似的需求,可以像使用单个模板一样创建文件 custom-reference.odt,将生成的文件重命名为例如 custom-reference-draft.odt 这样的名字,然后在 LibreOffice Writer 中打开它并修改样式。对你需要的每个模板重复此过程。

接下来,将文件复制到家目录中。如果你愿意,你甚至可以将它们放在 .pandoc 文件夹中。

要在转换时选择特定模板,你需要在终端中运行此命令:

pandoc -t odt file-name.md --reference-doc=path-to-your-file/custom-template.odt -o file-name.odt

改变 custom-template.odt 为你的模板文件名。

结语

为了不用记住我不经常使用的一组选项,我拼凑了一些简单的、非常蹩脚的单行脚本,这些脚本封装了每个模板的选项。例如,我运行脚本 todraft.sh 以使用带有 DRAFT 水印的模板创建文字处理器文档。你可能也想要这样做。

以下是使用包含 DRAFT 水印的模板的脚本示例:

pandoc -t odt $1.md -o $1.odt --reference-doc=~/Documents/pandoc-templates/custom-reference-draft.odt

使用 pandoc 是一种不必放弃命令行生活而以人们要求的格式提供文档的好方法。此工具也不仅适用于 Markdown。我在本文中讨论的内容还可以让你在各种标记语言之间创建和转换文档。有关更多详细信息,请参阅前面链接的 pandoc 官网


via: https://opensource.com/article/19/5/convert-markdown-to-word-pandoc

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

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

Markdown 是一种轻量级标记语言,可以在添加格式后以纯文本格式查看时依然保持可读性。Markdown(和 Markdown 衍生物)被广泛用作 GitHub 和 pagure 等服务上格式化文档的主要形式。根据其设计,可以在文本编辑器中轻松创建和编辑 Markdown,但是,有许多编辑器可以提供 Markdown 标记的格式化预览,或提供 Markdown 语法高亮显示。

本文介绍了针对 Fedora 平台的 3 个桌面应用程序,以帮助编辑 Markdown。

UberWriter

UberWriter 是一个小巧的 Markdown 编辑器和预览器,允许你以文本方式编辑,并预览渲染的文档。

该编辑器本身具有内置的内联预览,因此标记为粗体的文本以粗体显示。编辑器还提供图像、公式、脚注等标记的内联预览。按住 Ctrl 键单击其中的一个标记可以即时预览要显示的元素。

除了编辑器功能外,UberWriter 还具有全屏模式和聚焦模式,有助于最大限度地减少干扰。焦点模式将以灰色显示除当前段落以外的所有内容,以帮助你专注于文档中当前元素。

从第三方 Flathub 存储库安装 UberWriter 到 Fedora 平台。在将系统设置为从 Flathub 安装后,可以直接从 Software 应用程序中安装它。

Marker

Marker 是一个 Markdown 编辑器,它提供了一个简单的文本编辑器来编写 Markdown,并提供渲染文档的实时预览。界面采用分屏设计,左侧为编辑器,右侧为实时预览。

此外,Marker 允许你以各种格式导出文档,包括 HTML、PDF 和开放文档格式(ODF)。

从第三方 Flathub 存储库安装 Marker 到 Fedora 平台。在将系统设置为从 Flathub 安装后,可以直接从 Software 应用程序中安装它。

Ghostwriter

以前的编辑更专注于最小的用户体验,Ghostwriter 提供了更多的功能和选项。Ghostwriter 提供了一个文本编辑器,当你以 Markdown 格式书写时,编辑器将 Markdown 部分样式化。粗体标记文本显示为粗体,标题标记显示为较大的字体,以帮助编写 Markdown 标记。

它还提供了一个分屏,包含渲染文档的实时更新预览。

Ghostwriter 还包括一系列其他功能,包括能够选择渲染预览的 Markdown 风格,以及用于渲染预览的样式表。

此外,它还提供了一个格式菜单(和键盘快捷键)来插入一些频繁的 Markdown 标记,如粗体、项目符号和斜体。

从第三方 Flathub 存储库安装 Ghostwriter 到 Fedora 平台。在将系统设置为从 Flathub 安装后,可以直接从 Software 应用程序中安装它。


via: https://fedoramagazine.org/applications-for-writing-markdown/

作者:Ryan Lerch 选题:lujun9972 译者:murphyzhao 校对:wxy

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

有很多适用于 Linux 的 Markdown 编辑器,并且还在继续增加。问题是,像 Boostnote 一样,大多数是为编码人员设计的,可能不会受到非技术人员的欢迎。让我们看一个想要替代 Word 和昂贵的文字处理器,适用于非技术人员的 Markdown 编辑器。我们来看看 Zettlr 吧。

Zettlr Markdown 编辑器

Zettlr Light Mode

我可能在网站上提到过一两次,我更喜欢用 Markdown 写下我的所有文档。它易于学习,不会让你受困于专有文档格式。我还在我的适合作者的开源工具列表中提到了 Markdown 编辑器。

我用过许多 Markdown 编辑器,但是我一直有兴趣尝试新的。最近,我遇到了 Zettlr,一个开源 Markdown 编辑器。

Zettlr 是一位名叫 Hendrik Erz 的德国社会学家/政治理论家创建的。Hendrik 创建了 Zettlr,因为他对目前的文字处理器感到不满意。他想要可以让他“专注于写作和阅读”的编辑器。

在发现 Markdown 之后,他在不同的操作系统上尝试了几个 Markdown 编辑器。但它们都没有他想要的东西。根据 Hendrik 的说法,“但我不得不意识到没有为高效组织大量文本而写的编辑器。大多数编辑都是由编码人员编写的,因此可以满足工程师和数学家的需求。没有为我这样的社会科学、历史或政治学的学生的编辑器。“

所以他决定创造自己的。2017 年 11 月,他开始编写 Zettlr。

Zettlr About

Zettlr 功能

Zettlr 有许多简洁的功能,包括:

  • Zotero 数据库导入源并在文档中引用它们 * 使用可选的行屏蔽,让你无打扰地专注于写作 * 支持代码高亮 * 使用标签对信息进行排序 * 能够为该任务设定写作目标 * 查看一段时间的写作统计 * 番茄钟计时器 * 浅色/深色主题 * 使用 reveal.js 创建演示文稿 * 快速预览文档 * 可以在一个项目文件夹中搜索 Markdown 文档,并用热图展示文字搜索密度。 * 将文件导出为 HTML、PDF、ODT、DOC、reStructuredText、LaTex、TXT、Emacs ORG、TextBundle 和 Textpack * 将自定义 CSS 添加到你的文档

当我写这篇文章时,一个对话框弹出来告诉我最近发布了 1.3.0 beta。此测试版将包括几个新的主题,以及一大堆修复,新功能和改进。

Zettlr Night Mode

安装 Zettlr

目前,唯一可安装 Zettlr 的 Linux 存储库是 AUR。如果你的 Linux 发行版不是基于 Arch 的,你可以从网站上下载 macOS、Windows、Debian 和 Fedora 的安装程序

对 Zettlr 的最后一点想法

注意:为了测试 Zettlr,我用它来写这篇文章。

Zettlr 有许多我希望我之前选择的编辑器 (ghostwriter) 有的简洁的功能,例如为文档设置字数目标。我也喜欢在不打开文档的情况下预览文档的功能。

Zettlr Settings

我也遇到了几个问题,但这些更多的是因为 Zettlr 与 ghostwriter 的工作方式略有不同。例如,当我尝试从网站复制引用或名称时,它会将内嵌样式粘贴到 Zettlr 中。幸运的是,它有一个“不带样式粘贴”的选项。有几次我在打字时有轻微的延迟。但那可能是因为它是一个 Electron 程序。

总的来说,我认为 Zettlr 是第一次使用 Markdown 用户的好选择。它有许多 Markdown 编辑器已有的功能,并为那些只使用过文字处理器的用户增加了一些功能。

正如 Hendrik 在 Zettlr 网站中所说的那样,“让自己摆脱文字处理器的束缚,看看你的写作过程如何通过身边的技术得到改善!”

如果你觉得 Zettlr 有用,请考虑支持 Hendrik。正如他在网站上所说,“它是免费的,因为我不相信激烈竞争、早逝的创业文化。我只是想帮忙。”

你有没有用过 Zettlr?你最喜欢的 Markdown 编辑器是什么?请在下面的评论中告诉我们。

如果你觉得这篇文章有趣,请在社交媒体,Hacker News 或 Reddit 上分享它。


via: https://itsfoss.com/zettlr-markdown-editor/

作者:John Paul 选题:lujun9972 译者:geekpi 校对:wxy

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

如果你正在寻找一种简便的方法去格式化 Markdown 文本,那么这些编辑器可能会满足你的需求。

我的文章、散文、博客等等基本上都是在文本编辑器上使用 Markdown 写作的。当然,我不是唯一使用 Markdown 写作的人。不仅仅无数的人在使用 Markdown,而且也产生了许多服务于 Markdown 的工具。

谁能想到由 John Gruber 和之后的 Aaron Schwartz 创造的一种格式化网页文档的简便的方法如此的受欢迎呢?

我的大多数协作都是在文本编辑器上进行,我能理解为什么 Markdown 编辑器会如此受欢迎 —— 可以快速格式化,可以轻便的将文档转换为其他的格式,可以实时预览。

如果你想用 Markdown 和寻找一个专用的 Markdown 编辑器,那么这里有四个开源编辑器可能会让你写作更加轻松。

Ghostwriter

在我使用过的或试过的 Markdown 编辑器中 Ghostwriter 能排进前三。我已经使用或试了不少。

作为一个编辑器,Ghostwriter 就像一个画布,你可以手动进行编辑和添加格式。如果你不想这么做或者只想学习 Markdown 或者不知道如何添加,你可以从 Ghostwriter 的格式化菜单中选择你想要的格式。

一般的,它只有一个基本的格式:列表、字符格式化和缩进。所以你必须手动的添加标题、代码。而且它有一个有趣的任务列表选项,很多人都在用 Markdown 去创造任务列表,这个功能可以让你更加容易去创造和维护任务列表。

Ghostwriter 区别于其他的 Markdown 编辑器的是它有更多的导出选项。你可以选择你想使用的 Markdown 编译器,包括 SundownPandocDiscount。只需要点击两次,你可以轻松的将你写的内容转换为 HTML5、ODT、EPUB、LaTeX、PDF 或 Word 文档。

Abricotine

如果喜欢简洁的 Markdown 编辑器,你会爱上 Abricotine。但是不要让它的简单性欺骗了你;Abricotine 包含了很多强大的功能。

与其他的编辑器一样,你可以手动格式化文档或使用它的格式化菜单或插入菜单。Abricotine 有一个插入 GitHub 式 Markdown 表格的菜单。它预装了 16 个表样式,你可以在你需要的地方添加行或列。如果这个表看起来有点复杂,你可以使用 Ctrl+Shift+B 去使它看起来更整洁优美。

Abricotine 可以自动显示图片、连接和数学公式。当然你也可以关闭这些选项。可惜的是,这个编辑器只能导出为 HTML 格式。

Mark Text

像 Abricotine 一样,Mark Text 也是一个简洁的 Markdown 编辑器。它有一些你可能没有预料到但能够很好的处理 Markdown 文档的功能。

Mark Text 有点奇怪,它没有菜单或工具条。你需要点击编辑器左上角的弹出式菜单得到命令和功能。它就是让你专注于你的内容。

虽然当你添加内容后,可以在预览区实时看到你所写的内容,但它仍然是一个半所见即所得的编辑器。Mark Text 支持 GitHub 式 Markdown 格式,所以你可以添加表和语法高亮的代码块。在缺省的预览中,编辑器会显示你文档的所有图片。

与 Ghostwriter 相比,你只能将你的文档保存为 HTML 或 PDF 格式。这个输出看起来也不是很糟糕。

Remarkable

Remarkable 复杂性介乎于 Ghostwriter 和 Abricotine 或 Mark Text 之间。它有一个带点现代风格的双栏界面。它有一些有用的特点。

你注意到的第一件事是它受到 Material Design 启发的界面外观。它不是每一个人都能习惯的,老实说:我花费了很多时间去适应它。一旦你适应了,它使用起来很简单。

你可以在工具条和菜单上快速访问格式化功能。你可以使用内置的 11 种 CSS 样式或你自己创造的去定制预览框的样式。

Remarkable 的导出选项是有限的 —— 你只能导出为 HTML 或 PDF 格式文件。然而你可以复制整个文档或挑选一部分作为 HTML,粘贴到另一个文档或编辑器中。

你有最喜爱的 Markdown 编辑器吗?为什么不在评论区分享它呢?


via: https://opensource.com/article/18/11/markdown-editors

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

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

用这个有用工具从 Markdown 文件创建一个基础的网站。

有很多理由喜欢 Markdown,这是一门简单的语言,有易于学习的语法,它可以与任何文本编辑器一起使用。使用像 Pandoc 这样的工具,你可以将 Markdown 文本转换为各种流行格式,包括 HTML。你还可以在 Web 服务器中自动执行转换过程。由 TimoDörr 创建的名为 MDwiki 的 HTML5 和 JavaScript 应用可以将一堆 Markdown 文件在浏览器请求它们时转换为网站。MDwiki 网站包含一个操作指南和其他信息可帮助你入门:

 title=

Mdwiki 网站的样子。

在 Web 服务器内部,基本的 MDwiki 站点如下所示:

 title=

该站点的 web 服务器文件夹的样子

我将此项目的 MDwiki HTML 文件重命名为 START.HTML。还有一个处理导航的 Markdown 文件和一个 JSON 文件来保存一些配置设置。其他的都是网站内容。

虽然整个网站设计被 MDwiki 固定了,但内容、样式和页面数量却没有。你可以在 MDwiki 站点查看由 MDwiki 生成的一系列不同站点。公平地说,MDwiki 网站缺乏网页设计师可以实现的视觉吸引力 —— 但它们是功能性的,用户应该平衡其简单的外观与创建和编辑它们的速度和简易性。

Markdown 有不同的风格,可以针对不同的特定目的扩展稳定的核心功能。MDwiki 使用 GitHub 风格 Markdown,它为流行的编程语言添加了格式化代码块和语法高亮等功能,使其非常适合生成程序文档和教程。

MDwiki 还支持 “gimmick”,它增加了如嵌入 YouTube 视频和显示数学公式等额外功能。如果在某些项目中需要它们,这些值得探索。我发现 MDwiki 是创建技术文档和教育资源的理想工具。我还发现了一些可能不会立即显现出来的技巧和 hack。

当部署在 Web 服务器中时,MDwiki 可与任何现代 Web 浏览器一起使用。但是,如果你使用 Mozilla Firefox 访问 MDwiki,那么就不需要 Web 服务器。大多数 MDwiki 用户会选择在 Web 服务器上部署完整的项目,以避免排除潜在用户,但只需使用文本编辑器和 Firefox 即可完成开发和测试。任何现代浏览器都可以读取加载到 Moodle 虚拟学习环境(VLE)中的完整的 MDwiki 项目,这在教育环境中非常有用。 (对于其他 VLE 软件,这可能也是如此,但你应该测试它。)

MDwiki 的默认配色方案并非适用于所有项目,但你可以将其替换为从 Bootswatch.com 下载的其他主题。为此,只需在编辑器中打开 MDwiki HTML 文件,找到 extlib/css/bootstrap-3.0.0.min.css,然后插入下载的 Bootswatch 主题。还有一个 MDwiki gimmick,让用户在浏览器中载入 MDwiki 后,选择 Bootswatch 主题来替换默认值。我经常与有视力障碍的用户一起工作,他们倾向于喜欢高对比度的主题,在深色背景上使用白色文字。

 title=

MDwiki 页面使用 Bootswatch Superhero 主题

MDwiki、Markdown 文件和静态图像可以用于许多目的。但是,你有时可能希望包含 JavaScript 幻灯片或反馈表单。Markdown 文件可以包含 HTML 代码,但将 Markdown 与 HTML 混合会让人感到困惑。一种解决方案是在单独的 HTML 文件中创建所需的功能,并将其显示在带有 iframe 标记的 Markdown 文件中。我从 Twine Cookbook 知道了这个想法,它是 Twine 交互式小说引擎的支持站点。Twine Cookbook 实际上并没有使用 MDwiki,但结合 Markdown 和 iframe 标签开辟了广泛的创作可能性。

这是一个例子:

此 HTML 将显示由 Markdown 文件中的 Twine 交互式小说引擎创建的 HTML 页面。

<iframe height="400" src="sugarcube_dungeonmoving_example.html" width="90%"></iframe>

MDwiki 生成的站点结果如下所示:

简而言之,MDwiki 是一个出色的小应用,可以很好地实现其目的。


via: https://opensource.com/article/18/8/markdown-html-publishing

作者:Peter Cheer 选题:lujun9972 译者:geekpi 校对:wxy

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

这篇指南介绍如何使用 Pandoc 将文档转换为多种不同的格式。

Pandoc 是一个命令行工具,用于将文件从一种标记语言转换为另一种标记语言。标记语言使用标签来标记文档的各个部分。常用的标记语言包括 Markdown、ReStructuredText、HTML、LaTex、ePub 和 Microsoft Word DOCX。

简单来说,Pandoc 允许你将一些文件从一种标记语言转换为另一种标记语言。典型的例子包括将 Markdown 文件转换为演示文稿、LaTeX,PDF 甚至是 ePub。

本文将解释如何使用 Pandoc 从单一标记语言(在本文中为 Markdown)生成多种格式的文档,引导你完成从 Pandoc 安装,到展示如何创建多种类型的文档,再到提供有关如何编写易于移植到其他格式的文档的提示。

文中还将解释使用元信息文件对文档内容和元信息(例如,作者姓名、使用的模板、书目样式等)进行分离的意义。

Pandoc 安装和要求

Pandoc 默认安装在大多数 Linux 发行版中。本教程使用 pandoc-2.2.3.2 和 pandoc-citeproc-0.14.3。如果不打算生成 PDF,那么这两个包就足够了。但是,我建议也安装 texlive,这样就可以选择生成 PDF 了。

通过以下命令在 Linux 上安装这些程序:

sudo apt-get install pandoc pandoc-citeproc texlive

您可以在 Pandoc 的网站上找到其他平台的 安装说明

我强烈建议安装 pandoc-crossref,这是一个“用于对图表,方程式,表格和交叉引用进行编号的过滤器”。最简单的安装方式是下载 预构建的可执行文件,但也可以通过以下命令从 Haskell 的软件包管理器 cabal 安装它:

cabal update
cabal install pandoc-crossref

如果需要额外的 Haskell 安装信息,请参考 pandoc-crossref 的 GitHub 仓库。

几个例子

我将通过解释如何生成三种类型的文档来演示 Pandoc 的工作原理:

  • 由包含数学公式的 LaTeX 文件创建的网页
  • 由 Markdown 文件生成的 Reveal.js 幻灯片
  • 混合 Markdown 和 LaTeX 的合同文件

创建一个包含数学公式的网站

Pandoc 的优势之一是以不同的输出文件格式显示数学公式。例如,我们可以从包含一些数学符号(用 LaTeX 编写)的 LaTeX 文档(名为 math.tex)生成一个网页。

math.tex 文档如下所示:

% Pandoc math demos

$a^2 + b^2 = c^2$

$v(t) = v_0 + \frac{1}{2}at^2$

$\gamma = \frac{1}{\sqrt{1 - v^2/c^2}}$

$\exists x \forall y (Rxy \equiv Ryx)$

$p \wedge q \models p$

$\Box\diamond p\equiv\diamond p$

$\int_{0}^{1} x dx = \left[ \frac{1}{2}x^2 \right]_{0}^{1} = \frac{1}{2}$

$e^x = \sum_{n=0}^\infty \frac{x^n}{n!} = \lim_{n\rightarrow\infty} (1+x/n)^n$

通过输入以下命令将 LaTeX 文档转换为名为 mathMathML.html 的网站:

pandoc math.tex -s --mathml  -o mathMathML.html

参数 -s 告诉 Pandoc 生成一个独立的网页(而不是网页片段,因此它将包括 HTML 中的 head 和 body 标签),-mathml 参数强制 Pandoc 将 LaTeX 中的数学公式转换成 MathML,从而可以由现代浏览器进行渲染。

看一下 网页效果代码,代码仓库中的 Makefile 使得运行更加简单。

制作一个 Reveal.js 幻灯片

使用 Pandoc 从 Markdown 文件生成简单的演示文稿很容易。幻灯片包含顶级幻灯片和下面的嵌套幻灯片。可以通过键盘控制演示文稿,从一个顶级幻灯片跳转到下一个顶级幻灯片,或者显示顶级幻灯片下面的嵌套幻灯片。 这种结构在基于 HTML 的演示文稿框架中很常见。

创建一个名为 SLIDES 的幻灯片文档(参见 代码仓库)。首先,在 后面添加幻灯片的元信息(例如,标题、作者和日期):

% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017

这些元信息同时也创建了第一张幻灯片。要添加更多幻灯片,使用 Markdown 的一级标题(在下面例子中的第5行,参考 Markdown 的一级标题 )生成顶级幻灯片。

例如,可以通过以下命令创建一个标题为 “Case Study”、顶级幻灯片名为 “Wine Management System” 的演示文稿:

% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017

# Wine Management System

使用 Markdown 的二级标题将内容(比如包含一个新管理系统的说明和实现的幻灯片)放入刚刚创建的顶级幻灯片。下面添加另外两张幻灯片(在下面例子中的第 7 行和 14 行 ,参考 Markdown 的二级标题 )。

  • 第一个二级幻灯片的标题为 “Idea”,并显示瑞士国旗的图像
  • 第二个二级幻灯片的标题为 “Implementation”
% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017

# Wine Management System

## <img src="img/SwissFlag.png" style="vertical-align:middle"/> Idea

## Implementation

我们现在有一个顶级幻灯片(#Wine Management System),其中包含两张幻灯片(## Idea## Implementation)。

通过创建一个由符号 > 开头的 Markdown 列表,在这两张幻灯片中添加一些内容。在上面代码的基础上,在第一张幻灯片中添加两个项目(第 9-10 行),第二张幻灯片中添加五个项目(第 16-20 行):

% Case Study
% Kiko Fernandez Reyes
% Sept 27, 2017

# Wine Management System

## <img src="img/SwissFlag.png" style="vertical-align:middle"/> Idea

>- Swiss love their **wine** and cheese
>- Create a *simple* wine tracker system

![](img/matterhorn.jpg)

## Implementation

>- Bottles have a RFID tag
>- RFID reader (emits and read signal)
>- **Raspberry Pi**
>- **Server (online shop)**
>- Mobile app

上面的代码添加了马特洪峰的图像,也可以使用纯 Markdown 语法或添加 HTML 标签来改进幻灯片。

要生成幻灯片,Pandoc 需要引用 Reveal.js 库,因此它必须与 SLIDES 文件位于同一文件夹中。生成幻灯片的命令如下所示:

pandoc -t revealjs -s --self-contained SLIDES \
-V theme=white -V slideNumber=true -o index.html

上面的 Pandoc 命令使用了以下参数:

  • -t revealjs 表示将输出一个 revealjs 演示文稿
  • -s 告诉 Pandoc 生成一个独立的文档
  • --self-contained 生成没有外部依赖关系的 HTML 文件
  • -V 设置以下变量:

    • theme=white 将幻灯片的主题设为白色
    • slideNumber=true 显示幻灯片编号
  • -o index.html 在名为 index.html 的文件中生成幻灯片

为了简化操作并避免键入如此长的命令,创建以下 Makefile:

all: generate

generate:
    pandoc -t revealjs -s --self-contained SLIDES \
    -V theme=white -V slideNumber=true -o index.html

clean: index.html
    rm index.html

.PHONY: all clean generate

可以在 这个仓库 中找到所有代码。

制作一份多种格式的合同

假设你正在准备一份文件,并且(这样的情况现在很常见)有些人想用 Microsoft Word 格式,其他人使用自由软件,想要 ODT 格式,而另外一些人则需要 PDF。你不必使用 OpenOffice 或 LibreOffice 来生成 DOCX 或 PDF 格式的文件,可以用 Markdown 创建一份文档(如果需要高级格式,可以使用一些 LaTeX 语法),并生成任何这些文件类型。

和以前一样,首先声明文档的元信息(标题、作者和日期):

% Contract Agreement for Software X
% Kiko Fernandez-Reyes
% August 28th, 2018

然后在 Markdown 中编写文档(如果需要高级格式,则添加 LaTeX)。例如,创建一个固定间隔的表格(在 LaTeX 中用 \hspace{3cm} 声明)以及客户端和承包商应填写的行(在 LaTeX 中用 \hrulefill 声明)。之后,添加一个用 Markdown 编写的表格。

创建的文档如下所示:

创建此文档的代码如下:

% Contract Agreement for Software X
% Kiko Fernandez-Reyes
% August 28th, 2018

...

### Work Order

\begin{table}[h]
\begin{tabular}{ccc}
The Contractor & \hspace{3cm} & The Customer \\
& & \\
& & \\
\hrulefill & \hspace{3cm} & \hrulefill \\
%
Name & \hspace{3cm} & Name \\
& & \\
& & \\
\hrulefill & \hspace{3cm} & \hrulefill \\
...
\end{tabular}
\end{table}

\vspace{1cm}

+--------------------------------------------|----------|-------------+
| Type of Service                            | Cost     |     Total   |
+:===========================================+=========:+:===========:+
| Game Engine                                | 70.0     | 70.0        |
|                                            |          |             |
+--------------------------------------------|----------|-------------+
|                                            |          |             |
+--------------------------------------------|----------|-------------+
| Extra: Comply with defined API functions   | 10.0     | 10.0        |
|        and expected returned format        |          |             |
+--------------------------------------------|----------|-------------+
|                                            |          |             |
+--------------------------------------------|----------|-------------+
| **Total Cost**                             |          | **80.0**    |
+--------------------------------------------|----------|-------------+

要生成此文档所需的三种不同输出格式,编写如下的 Makefile:

DOCS=contract-agreement.md

all: $(DOCS)
    pandoc -s $(DOCS) -o $(DOCS:md=pdf)
    pandoc -s $(DOCS) -o $(DOCS:md=docx)
    pandoc -s $(DOCS) -o $(DOCS:md=odt)

clean:
    rm *.pdf *.docx *.odt

.PHONY: all clean

4 到 7 行是生成三种不同输出格式的具体命令:

如果有多个 Markdown 文件并想将它们合并到一个文档中,需要按照希望它们出现的顺序编写命令。例如,在撰写本文时,我创建了三个文档:一个介绍文档、三个示例和一些高级用法。以下命令告诉 Pandoc 按指定的顺序将这些文件合并在一起,并生成一个名为 document.pdf 的 PDF 文件。

pandoc -s introduction.md examples.md advanced-uses.md -o document.pdf

模板和元信息

编写复杂的文档并非易事,你需要遵循一系列独立于内容的规则,例如使用特定的模板、编写摘要、嵌入特定字体,甚至可能要声明关键字。所有这些都与内容无关:简单地说,它就是元信息。

Pandoc 使用模板生成不同的输出格式。例如,有一个 LaTeX 的模板,还有一个 ePub 的模板,等等。这些模板的元信息中有未赋值的变量。使用以下命令找出 Pandoc 模板中可用的元信息:

pandoc -D FORMAT

例如,LaTex 的模版是:

pandoc -D latex

按照以下格式输出:

$if(title)$
\title{$title$$if(thanks)$\thanks{$thanks$}$endif$}
$endif$
$if(subtitle)$
\providecommand{\subtitle}[1]{}
\subtitle{$subtitle$}
$endif$
$if(author)$
\author{$for(author)$$author$$sep$ \and $endfor$}
$endif$
$if(institute)$
\providecommand{\institute}[1]{}
\institute{$for(institute)$$institute$$sep$ \and $endfor$}
$endif$
\date{$date$}
$if(beamer)$
$if(titlegraphic)$
\titlegraphic{\includegraphics{$titlegraphic$}}
$endif$
$if(logo)$
\logo{\includegraphics{$logo$}}
$endif$
$endif$

\begin{document}

如你所见,输出的内容中有标题、致谢、作者、副标题和机构模板变量(还有许多其他可用的变量)。可以使用 YAML 元区块轻松设置这些内容。 在下面例子的第 1-5 行中,我们声明了一个 YAML 元区块并设置了一些变量(使用上面合同协议的例子):

---
title: Contract Agreement for Software X
author: Kiko Fernandez-Reyes
date: August 28th, 2018
---

(continue writing document as in the previous example)

这样做非常奏效,相当于以前的代码:

% Contract Agreement for Software X
% Kiko Fernandez-Reyes
% August 28th, 2018

然而,这样做将元信息与内容联系起来,也即 Pandoc 将始终使用此信息以新格式输出文件。如果你将要生成多种文件格式,最好要小心一点。例如,如果你需要以 ePub 和 HTML 的格式生成合同,并且 ePub 和 HTML 需要不同的样式规则,该怎么办?

考虑一下这些情况:

  • 如果你只是尝试嵌入 YAML 变量 css:style-epub.css,那么将从 HTML 版本中移除该变量。这不起作用。
  • 复制文档显然也不是一个好的解决方案,因为一个版本的更改不会与另一个版本同步。
  • 你也可以像下面这样将变量添加到 Pandoc 命令中:
pandoc -s -V css=style-epub.css document.md document.epub
pandoc -s -V css=style-html.css document.md document.html

我的观点是,这样做很容易从命令行忽略这些变量,特别是当你需要设置数十个变量时(这可能出现在编写复杂文档的情况中)。现在,如果将它们放在同一文件中(meta.yaml 文件),则只需更新或创建新的元信息文件即可生成所需的输出格式。然后你会编写这样的命令:

pandoc -s meta-pub.yaml document.md document.epub
pandoc -s meta-html.yaml document.md document.html

这是一个更简洁的版本,你可以从单个文件更新所有元信息,而无需更新文档的内容。

结语

通过以上的基本示例,我展示了 Pandoc 在将 Markdown 文档转换为其他格式方面是多么出色。


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

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

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