markdown/pandoc的全站编译？ [关闭]答案

【问题标题】：Whole site compilation of markdown/pandoc? [closed]markdown/pandoc的全站编译？ [关闭]
【发布时间】：2013-03-14 06:19:52
【问题描述】：

使用Sphinx-doc，您可以创建一堆 ReStructureText 文件，其中一个 index.rst 文件包含一个目录宏，该宏会自动从其他包含的文件生成目录，还有一个 conf.py作为编译配置。然后，您可以将该批次编译成单个 python-doc 样式的站点，其中包含索引、导航工具和搜索功能。

有没有类似的markdown工具（最好是pandoc风格的markdown）？

【问题讨论】：

是否还有一些 (markdown) 文档工具，可以像 Sphinx 一样简单地生成 PDF 和 ePub？
@white_gecko 在Markdown 中编辑，使用pandoc 转换为XHTML，最后使用PrinceXML 转换为PDF，您可能会或可能不会免费使用（请参阅CSO license）。再次，查看my website 了解详情。有一个名为wkhtmltopdf 的开源替代方案，但它不擅长分页。

标签： documentation markdown pandoc pelican

【解决方案1】：

一些与 Markdown 配合使用的静态网站生成器：

Jekyll 非常受欢迎，也是 GitHub pages 背后的引擎。
Python 变体：Hyde 或 Pelican
nanoc（在 GitHub API documentation 中使用 f.ex.）
Middlemanapp: 也许是最好的？

我认为它们都没有使用 pandoc（可能是因为它是用 Haskell 编写的），但它们都使用增强的 Markdown 语法或者可以配置为使用 pandoc。

其他从 Markdown 生成网站的有趣方法：

Markdown-Wiki 基于文件：f.ex。 Gollum，GitHub 也使用的 Wiki-Engine
Telegram：商业；由 Lift-Scala 框架的发明者 David Pollak 撰写

使用 Pandoc 的引擎：

静态站点生成器的最终列表

静态网站生成器概览：http://staticsitegenerators.net/

【讨论】：

Hyde 基本上是一个 CMS，对吧？我不想要一些我不得不离开的东西。不过，其他一些看起来很有趣，感谢您的列表！
据我所知，Hyde 也像 Jekyll 一样生成静态 HTML。
对于那些追随我的人：Pelican 很酷，但它针对的是博客，而不是像 sphinx 那样的静态网站。
@naught101 你最后是为了什么？我正在寻找类似的解决方案。

【解决方案2】：

Pandoc、GNU make 和 sed 命令，以及一些 CSS 是您从 Markdown 开始完全自动化创建静态网站所需的一切。

Pandoc 提供三个命令行选项，可以提供页面之间的导航以及基于页面内标题创建目录 (TOC)。使用 CSS，您可以使导航和 TOC 的外观和行为符合您的要求。

-B 文件，--include-before-body=FILE

在文档正文的开头逐字包含 FILE 的内容（例如，在 HTML 中的标记之后，或 LaTeX 中的 \begin{document} 命令之后）。这可用于在 HTML 文档中包含导航栏或横幅。此选项可重复使用以包含多个文件。它们将包含在指定的顺序中。暗示 --standalone。

--toc，--目录

包括一个自动生成的目录。

--toc-depth=NUMBER

指定要包含在目录中的部分级别数。默认为 3（表示将在内容中列出级别 1、2 和 3 的标头）。

事实上，my personal website is built this way。查看其makefile 了解更多详情。它都是在GNU GPL version 3 下获得许可的免费开源软件。

【讨论】：

呃...这些 TOC 选项与 within 标记文件的标题有关。我说的是跨多个文件的目录，每个文件都是一个单独的页面。您的个人网站是一个页面...
@naught101 我已经编辑了我的答案。使用--include-before-body=FILE 选项可以轻松处理页面之间的导航。
不，你没有抓住重点。 Sphinx-doc 允许您将多个页面作为单独的文件编写，然后为每个页面生成一个 HTML 文件（在侧栏中有一个 TOC），以及一个完整页面的 TOC html 文件（即没有 .rst 源，但它自动生成）。这就是我要问的。
@naught101 那么 Sphinx-doc 确实比原始海报引用的一些引擎（Gouda、Rippledoc...）做得更多。
on4aa：我是 OP。不过，我发现这个问题不够清晰，并对其进行了编辑。

【解决方案3】：

如果您可以不使用 Pandoc，mkdocs 似乎可以满足您的需求。

如果你确实想使用 Pandoc 风格的 Markdown，你可以查看pdsite。我将其编写为一种使用更多输入格式（如 emacs org-mode）和没有 Python 依赖项的 mkdocs 样式站点生成的方法——您传入一个 Markdown 文件文件夹并得到一个 HTML 站点（包括自动生成的多级导航链接）。它类似于 Serge Stroobandt 的方法，因为它只是一个 shell 脚本（但它确实需要您安装 tree）。不幸的是，它还没有搜索功能，虽然添加起来并不难......

【讨论】：