一般建议都是使用数字进行排序,然后使用*.md
或者*.markdown
的形式直接传入pandoc命令进行编译即可(pandoc *.md > markdown_book.html
)
使用数字进行排序便于为pandoc输入文件的做法
带来的不便是,中间插入其他内容或者章节的时候需要很多调整:
01_preface.md
02_introduction.md
03_why_markdown_is_useful.md
04_limitations_of_markdown.md
05_conclusions.md
06_links.md
很多章节是嵌套有层次化的, 最直觉性的管理方式是使用目录, 但这样又会导致pandoc编译的时候资源引用错误,因为我们在编写的时候实际上使用的资源引用都是相对路径, 比如images/xx.png, 而如果我们嵌套了目录, 那么, 这个图片资源可能存在于chapter3/images/xx.png, 因为我们是在顶层目录执行pandoc命令的:
pandoc_compile_command.sh
preface.md
chapter1/
chapter2/
images/
xx.png
section1.md
section2.md
...
chapter3/
...
为了规避这种问题,我们要么就把所有md和images文件拉平(flatten)到同一个目录下面, 要么,就使用pandoc命令的时候,明确指定输入顺序, 但依然无法解决图片路径引用的在编写和编译期间的差异问题:
➜ pandoc_book_starter git:(master) ✗ pandoc -s -N --toc --toc-depth=4 --self-contained -c ~/FuqiangWorks/templates/pandoc/ivy.css "index.md" > "index.html"
File images/ipfs.jpeg not found in resource path
使用嵌套目录的形式管理层次化内容, 便于编写和管理, 在编译期间,使用某种filter机制, 将各个子目录的内容归并到同一个md文件, 同时修改图片引用地址, 最终从合并后的md文件进行编译。
filter主要做两个事情:
处理后的内容合并入md统一交给pandoc编译即可。
当然, 我们依然可以结合pandoc命令行的明确指定多输入文件的方式进一步细化前后的附录内容,比如preface,附录,参考资料等。
具体工程结构和使用可以参考已经开源到Github的实例项目模板: https://github.com/keevol/pandoc_book_starter
#标题
作为第一行, 否则pandoc在编译的时候很容易跟上一章或者上一节内容拼接的时候,格式上忽略放在第一行的标题;