Markdown to Ebook教程

1 . 目 录 致谢 README 空标题文档 An Introduction We are going to need a workflow Flavors of Markdown Leanpubbin’: A Brief Introduction To Leanpub LaTeXing Going Local Common Customizations Krambook: Build a Gem A Sublime Markdown Experience All the features of Leanpub Pitfalls Prepping for Publishing. Wrap Up 本文档使用 书栈(BookStack.CN) 构建 - 1 - 

2 .致谢 致谢 当前文档 《markdown to ebook（英文）》 由 进击的皇虫 使用 书栈(BookStack.CN) 进行构建，生成于 2018-05-11。 书栈(BookStack.CN) 仅提供文档编写、整理、归类等功能，以及对文档内容的生成和导出工 具。 文档内容由网友们编写和整理，书栈(BookStack.CN) 难以确认文档内容知识点是否错漏。如 果您在阅读文档获取知识的时候，发现文档内容有不恰当的地方，请向我们反馈，让我们共同携手， 将知识准确、高效且有效地传递给每一个人。 同时，如果您在日常生活、工作和学习中遇到有价值有营养的知识文档，欢迎分享到 书栈 (BookStack.CN) ，为知识的传承献上您的一份力量！ 如果当前文档生成时间太久，请到 书栈(BookStack.CN) 获取最新的文档，以跟上知识更新换 代的步伐。 文档地址：http://www.bookstack.cn/books/markdown-to-ebook 书栈官网：http://www.bookstack.cn 书栈开源：https://github.com/TruthHun 分享，让知识传承更久远！ 感谢知识的创造者，感谢知识的分享者，也感谢每一位阅读到此处的 读者，因为我们都将成为知识的传承者。 本文档使用 书栈(BookStack.CN) 构建 - 2 - 

3 .README README You’ll learn the following; What you need to know already Table of Contents Planned Chapters This book is currently in beta A quick note on licensing 来源(书栈小编注) This is a book on constructing ebooks using Markdown. No esoteric and complicated formats. No WYSIWYG editors. No PDF hell. Just plaintext. You’ll learn everything from generating a TOC to adding cover images. It’ll teach you the very workflow I used to write this book. A workflow that frees you from the constraints of writing in a complicated format that scarcely resembles text, or writing You’ll learn the following; The differences between various Markdown implementations How to take Markdown and turn it into; epub mobi pdf html How to work with code samples, codeblocks, images, TOC etc How to build custom Markdown extensions using Kramdown. For stuff like; code bubbles notes asides and other nifty little doodads How various html ebook format wrappers (such as ePub, mobi etc) work. No magic! Common markdown pitfalls (I documented all my failures while writing this book) Various techniques for previewing your Markdown output Sublime Text Previewing html previews 本文档使用 书栈(BookStack.CN) 构建 - 3 - 

4 .README automatic previews using the guard gem How to mirror the Leanpub workflow using local tools How to customize converters so you have full control of your in-between formats; laTeX (pdf) and HTML (ePub, mobi etc) The minimal laTeX you’ll need to get stuff done with PDF What you need to know already Some hacker skills are necessary to make full use of this book. To write books using Markdown you’ll need to be comfortable getting your hands dirty, breaking things and learning. This book doesn’t assume you’re skilled in any particular language but it assumes you are skilled in programming. Familiarity with your systems package manager will be necessary. Can you do this? $ homebrew install Or if you are on Linux this? $ sudo apt-get install If this leaves you scratching your head then you are not ready for this book. If you are left feeling comfortable and at ease, not queasy and fearful, then you are ready. Some rudimentary ability to read and edit Ruby will be necessary. If you are comfortable enough to edit Gemfiles and install gems using bundler then you should be fine. Table of Contents Hacker meet book. Book meet hacker We are going to need a workflow LaTeX Leanpub Flavors of Markdown Github flavored Markdown MultiMarkdown Markdown Extra You might be tempted Leanpubbin’ 本文档使用 书栈(BookStack.CN) 构建 - 4 - 

5 .README Leanpub Markdown flavor Previewing Leanpub locally LaTeXing Installing LaTeX Installing LaTeX Packages on Mac Installing LaTeX Packages on Ubuntu (and other Debians) Using Packages LaTeX: A Very Brief Introduction Custom LaTeX Styles Going local All the Markdown in One Creating PDFs Images and Your PDFs Common Customization My God, it’s full of Snippets Including Source Files With Kramdown Including Source Files With Pandoc Including Files via LaTeX Generating a Table of Contents Custom thing a ma bobs A key binding awaits A Sublime Markdown Experience Count my chars, measure my words, tell me the lines, express my worth Getting Sublime Pitfalls Markdown Issues LaTeX to PDF HTML, Epub, Mobi etc Prepping for Publishing Converting to epub From epub to mobi and beyond Cover Images Some brief notes on styling things Wrap Up Notes The End Planned Chapters Chapters on the following topics are planned; 本文档使用 书栈(BookStack.CN) 构建 - 5 - 

6 .README Using Quarto and PDFKit to generate PDFs from XHTML + CSS Web based books with runnable consoles and code samples 本文档使用 书栈(BookStack.CN) 构建 - 6 - 

7 .README This book is currently in beta It is considered to be about 90% complete and is still undergoing proofreading, editing and revision. The last 10% can make a big difference in the quality of a work so please be forgiving if it does not meet your expectations. A quick note on licensing This book is licensed under a MIT license and is open sourced on Github. This does not mean I want you to read it for free, in fact, I want it to be worth more to you. I recognize that the more permissively licensed the more valuable it becomes. The more free my work is to move the greater the potential impact it can have. My goal is to make the book as valuable to you as possible. So the less I limit you the better. Feel free to take my book and use it in whatever way you like, in whatever way furthers your life the most. I only ask that in return, you contribute back to me what I contributed to you. How much this work is worth to you is up for you to decide. I hope you find it’s a lot. You can purchase this book on Leanpub or if you like you can just drop me some bitcoin: 1csGsaDCFLRPPqugYjX93PEzaStuqXVMu or support me on Gittip ~K-2052 来源(书栈小编注) https://github.com/k2052/markdown-to-ebook 本文档使用 书栈(BookStack.CN) 构建 - 7 - 

8 .README 本文档使用 书栈(BookStack.CN) 构建 - 8 - 

9 .空标题文档 空标题文档 These are templates that get passed to Kramdown. 本文档使用 书栈(BookStack.CN) 构建 - 9 - 

10 .An Introduction An Introduction An Introduction What you need to know An Introduction Writing a book can be daunting, learning the tools to write a book can be even more daunting. A quick google search will turn up a multitude of services, tools, apps and frameworks designed to write a book. Apps like; iBooks, Adobe Acrobat, inDesign Skyreader, Kindle Publisher etc. Formats like; PDF, ePUB, LaTeX…. It’s not so far fetched that a writer when faced with this mess of “solutions” might simply choose a trusty old typewriter or even pen and paper. Or he might get so caught up writing tools for writing that he never gets the time to write. This book is a result of my search for a get out of the way method of writing ebooks. Something that keeps my focus on the writing and not on the process of writing. It doesn’t cover everything, it gives you just enough knowledge so you can focus on what matters, the writing. This book follows the hackers ethos of not obscuring things. Problem areas are not glossed over, they are put right out in the open, so you can learn from them. Where I struggled you will know I did and why I did. I wrote this book through countless frustrations with Markdown parsers, LaTeX packages and varying bugs; to ignore that would skip a crucial part of how I learned what I know. Most technical books appear smooth when read, but they were not written smoothly. To get that snippet down to something slim and slick requires a lot of breaking things and figuring out what doesn’t work. Making things look easy is hard work. I tried not to make things look easier than they are. By showing you my failures I hope to help you avoid them. This is not a book for those that like quick summaries and step by step 本文档使用 书栈(BookStack.CN) 构建 - 10 - 

11 .An Introduction processes. It’s a book for those that like to learn something. The only way to eliminate frustration is to internalize your knowledge, to make it so much a part of you that it cant be ignored. Unless you truly know how to do something then doing it is going to get in the way and take energy away from your writing. You cant for instance, be looking up how to create a section every time you want to create a section. Such a workflow will kill a book before it is even start. Things have to flow smoothly, without thought, so you can just write. With this in mind, I have kept the approach to tools as simple as possible, so they can be internalized as quickly as possible. Our book’ source files will be written in Markdown. Markdown is simple enough to internalize in a day and most importantly, it is flexible enough that it can be adapted to support a variety of extras. Kramdown has been chosen as our flavor/implementation of Markdown. This is for a few reasons; 1. It is used in a variety of publishing platforms (specifically Leanpub) 2. It closely resembles many other implementations like PHP Markdown Extended. 3. It’s well documented. 4. It’s coded in Ruby. Tools like pandoc are just as powerful as Kramdown but pandoc is unfortunately written in Haskell. Haskell would only increase the learning curve and add more annoying parts to getting our ebook published. What you need to know You wont need to know much to get through this book but you will need to be comfortable hacking around. Comfortable is a dangerous word for communication, one’s interpretation can vary greatly from what is intended. Let’s go over some examples to help clarify what I mean by comfortable Can you do this? {:lang=”sh”} 本文档使用 书栈(BookStack.CN) 构建 - 11 - 

12 .An Introduction homebrew install Or if you are on Linux this? {:lang=”sh”} sudo apt-get install If this leaves you scratching your head then you are not ready for this book. If you are left feeling comfortable and at ease, not queasy and fearful, then you are ready. Some rudimentary ability to read and edit Ruby will also be necessary. If you are comfortable enough to edit Gemfiles and install gems using bundler then you should be fine. 本文档使用 书栈(BookStack.CN) 构建 - 12 - 

13 .We are going to need a workflow We are going to need a workflow We are going to need a workflow Where will we distribute the book? What final format does it need to be in when distributed? LaTeX Leanpub We are going to need a workflow I’m pulled in a thousand different directions by a thousand different solutions. iBooks Author looks nice. Nathan Barry went with that right? I think that is also how Josh Long wrote Execute. But what about epub? Isn’t epub just html at its core? Maybe I’ll write in HTML and use an HTML to PDF converter? That would allow me to craft all sorts of customizations in CSS. I could really style things awesomely. I could release a web version with fancy JS stuff and blow people’s minds with a really unique ebook release. But what about organization of my writings — writing stuff in pure HTML is going to be a mess. I guess I could use a static site generator and write in a templating language to keeps things organized into chapters. But maybe I should use a ebook authoring tool that handles this for me? What about Scrivener? Don’t screenplay authors use that? What if I want to deliver a screenplay for my book in case they decide to adapt into a movie? Choosing a workflow from a place of ignorance is an exercise in futility. Any choice we make will be clouded by a lack of knowledge, too many options and possibly delusions of grandeur. If we want to find a workflow that works we are going to have start with very basic questions. Questions we can see the answers to immediately. If we answer the simple questions first then the complex ones will become clearer. Answering some basic questions will give us constraints and illuminate the path ahead. 本文档使用 书栈(BookStack.CN) 构建 - 13 - 

14 .We are going to need a workflow Where will we distribute the book? For distribution it would be nice to have something that works well for the writing phase as well as the publishing phase. Perhaps even something that generates our ebooks from our source formats for us. Such a service exists and it’s called Leanpub. What does Leanpub use as its source format? Leanpub uses Markdown. Thus, we will need to use Markdown; we now have our first constraint. What final format does it need to be in when distributed? There are a zillion different options for ebook formats so whatever we choose it’s going to have to be capable of converting into a variety of formats. We will need something that can go into PDF, epub, kindle and mobi formats. It just so happens that with the exception of PDF all these formats are HTML at there core. What is a good option for writing HTML ebooks? Markdown of course. Markdown is simple, flexible, looks great as plaintext and most importantly, it is built with HTML as the intended output format. How then do we turn Markdown into PDFs? The answer lies in LaTeX, which will be our in-between format of choice. LaTeX is to PDF as Markdown is to HTML. They’re best buds and get together all the time to just chat and mark things up. Does LaTeX mean we will have to maintain two separate formats? Nope. Markdown can be easily converted into LaTeX using tools like Kramdown. LaTeX LaTeX is one of those things you probably know about but have never bothered learning. I mean, it’s for technical 本文档使用 书栈(BookStack.CN) 构建 - 14 - 

15 .We are going to need a workflow papers right? When have you ever needed to write a technical paper. One day when you have the time, you plan to study it but not now. For now, you’ll just use Markdown. Markdown works for now, but one day you’re going to have to touch LaTeX if you want to move beyond the HTML realm. I could cover LaTeX the normal way; mention the apps you use to use it, the commands you use to install it, the syntax you use to craft it, and then send you on your way. Most books on LaTeX are written this way. I could tread the same ground other books do and I’m sure you’d get some benefit. After all, countless books cover things that way, it’s not a completely useless approach. You might even be motivated enough to play with LaTeX a bit. Perhaps you will even write a few a things in it. In the long run though, you’ll slowly find its usefulness lacking. Markdown will just be quicker and more productive. When you write Markdown you’ll get things done. When you use LaTeX you will feel like you’re fighting it; spending more time on your tool than on writing. When you truly need the power of LaTeX you’ll do what you always do, live without it or hack a solution onto your favorite Markdown parser. I know you’ll do this because I do it. We all do it. We learn new tech because we are curious, but if the logistics don’t work out, if the practicalities of using it don’t align with execution, actually getting stuff done, then we don’t use it. It’s the same reason we never blog on our amazing overly designed custom built blogging engines, it just isn’t productive. One day a Medium, Tumblr or Jekyll comes along and we finally take the plunge and simplify enough to just focus on our writing. Things need to be too easy or they won’t be made use of. Your tools need to blend into the background and get out of the way of creation or you’ll never use them. If we are actually going to make real use of LaTeX it’s going to have to work for us, not us for it. It will have to complement our workflow, not supplement it. We will adopt a workflow that makes LaTeX work for us. Leanpub 本文档使用 书栈(BookStack.CN) 构建 - 15 - 

16 .We are going to need a workflow Let’s visit Leanpub, get registered, and create a test book. After we get signed up, Leanpub will inform of us the basics. We will upload our ebook files via Dropbox. They will be written in plain text using Markdown. We will get a link sent to us for our first book. Get Dropbox setup if you haven’t already. I> You can utilize the web interface for Dropbox. No need to download/install. Visit the getting started page for your book leanpub.com/bookname/getting_started e.g https://leanpub.com/markdown-to- ebook/getting_started The first thing we can take away from this page is that we will use Markdown. If we incorporate fancy stuff it will be by customizing the conversion of our Markdown. I actually like this as it keeps our text straightforward and simple, we will only have to use convoluted LaTeX when absolutely necessary. We need to know a little about the Markdown flavor we are dealing with though. After some quick googling I found this HN comment: 1. Hey, co-founder of Leanpub here. 2. 3. If you're interested in the differences between Pandoc and Leanpub, there are two places to look. Leanpub is based 4. off of Kramdown, so there's the Kramdown documentation[1]. We have made a few extensions to Kramdown to support 5. things that books need, so you'll also want to look at the Leanpub manual[2]. 6. 7. If you have any questions, send us an email at hello@leanpub.com. 8. 9. [1]: http://kramdown.rubyforge.org/syntax.html [2]: https://leanpub.com/help/manual So, Leanpub uses Kramdown, this is good news. This makes incorporating Leanpub into our workflow even easier. 本文档使用 书栈(BookStack.CN) 构建 - 16 - 

17 .We are going to need a workflow 本文档使用 书栈(BookStack.CN) 构建 - 17 - 

18 .Flavors of Markdown Flavors of Markdown Flavors of Markdown Github flavored Markdown MultiMarkdown Markdown Extra Learn your Markdown Flavors of Markdown You might think you know Markdown, but chances are you only know a Markdown. The Markdown you know might not be the Markdown you get to use. All Markdown implementations handle the basics but you might not be aware of what the basics [^MarkdownExtensionsSpec] actually are. Automatic link parsing, for example, is not part of the standard, it’s just something that everyone and their biological birthing entity implements. There are three major flavors of extended Markdown you are likely to encounter. [^MarkdownExtensionsSpec]: An official extension spec is being worked on but the details are pretty sparse. See The Future of Markdown and this commit Github flavored Markdown This implementation has been made enormously popular by the ubiquity of Github in the development community. It has a few features not found in the original Markdown spec, namely; fenced code blocks and automatic link parsing. The de facto implementation of this flavor is redcarpet MultiMarkdown Like many Markdown flavors, MultiMarkdown originated as the de facto implementation of Markdown for a language; originally written for Perl, MultiMarkdown has since become a C 本文档使用 书栈(BookStack.CN) 构建 - 18 - 

19 .Flavors of Markdown library. It is one of the most well documented flavors but it lacks a decent adoption rate/userbase. Markdown Extra This variant came originally from PHP but has since been implemented in several languages. Markdown Extra has a few extra features like; footnotes, extensions, attribute lists etc. We will be using an implementation of Markdown Extra called Kramdown. There are two reasons for this: 1. Leanpub uses it. 2. It is written in Ruby which is easy to hack on. For the most part, the only two flavors you will have to deal with are Github’s and Markdown Extra. The differences between the two aren’t too significant. Most of what Github does is extra for Github and won’t effect your needs for ebook writing. Utilizing Github features just adds stuff when your Markdown is used on Github and utilizing Kramdown features just adds stuff when using Kramdown. The only difference you need to care about is the syntax for fenced code blocks. Github utilizes three `‘s and Kramdown uses three ~~~ . They look like: Github 1. ```ruby 2. require 'redcarpet' 3. markdown = Redcarpet.new("Hello World!") 4. puts markdown.to_html 5. ``` Kramdown 1. ~~~ ruby 2. require 'redcarpet' 3. markdown = Redcarpet.new("Hello World!") 4. puts markdown.to_html 5. ~~~ 本文档使用 书栈(BookStack.CN) 构建 - 19 - 

20 .Flavors of Markdown Since you cant modify the parsing on Github, if you plan to publish the same Markdown on Github and need the code highlighting you’ll need to modify Kramdown to use the same indicator as Github for starting and closing fenced code blocks. A> Alternatively you can just use indentation to specify your code blocks which is compatible across most A> implementations Changing ~ to a ` will get it parsing like Github. To do that just search for FENCED_CODEBLOCK_START in the Kramdown files. Monkey-patching is the simplest way to get the modification into Kramdown. In the interest of clarity, the following code snippet will accomplish said changes: {.lang=”ruby”} module Kramdown module Parser class Kramdown FENCED_CODEBLOCK_START = /^ {3,}/ FENCED_CODEBLOCK_MATCH = /^( {3,})\s?(\w+)?\s? \n(.?)^\1`\s*?\n/m end end end If you plan to use Leanpub you’ll need to utilize indented codeblocks instead. You’ll indent things using four spaces then manually specify your language using attribute lists. Like this: {:lang=”md”} This is a codeblock 1. {:lang="ruby"} 2. cats = 'demons' Beyond that, just follow the docs for Kramdown and you’ll be fine. Learn your Markdown 本文档使用 书栈(BookStack.CN) 构建 - 20 - 

21 .Flavors of Markdown You might be tempted to avoid learning Markdown and to add a Markdown GUI to your workflow. I urge you to resist that temptation. Jumping around in app menus for simple things like links and headings will kill your workflow. There is a reason why some writers from past eras still choose to use typewriters, being 100% comfortable with your tools is extremely important for productivity. You’ll need to know your Markdown inside and out if you ever hope to finish a book. Any app that attempts to replace the Markdown text process is going to interfere with your workflow in the long run. If you use Markdown apps only use them to complement your writing, with fancy previews and nifty publishing tools. Don’t use an app as a crutch. Using crutches will make you disabled. 本文档使用 书栈(BookStack.CN) 构建 - 21 - 

22 .Leanpubbin’: A Brief Introduction To Leanpub Leanpubbin’: A Brief Introduction To Leanpub Leanpubbin’: A Brief Introduction To Leanpub Leanpub Markdown flavor Images in Leanpub Previewing Leanpub locally Previewing with Sublime Previewing with VIM Previewing with Guard and HTML Other Preview Apps Leanpubbin’: A Brief Introduction To Leanpub The best way to get started with Leanpub is just to dive in — into a sample book. Visit https://leanpub.com/books/new and follow the steps. Leanpub will have created a folder for your ebook on Dropbox. Open up the folder. You should see convert_html and manuscript folders. Open up the manuscript folder. You will see a Book.txt file and a chapter1.txt file. Book.txt is an index of files. Files are ignored (not included in the book) until they’re added to the index. Leanpub takes Book.txt, parses it line by line, joins each file and then parses the joined file with Kramdown. At some point in the future Leanpub takes the Kramdown file and converts it to pdf, epub and mobi formats. If we wanted to create the structure for a Leanpub book manually we could do the following: Create the manuscript folder: {:lang=”sh”} $ mkdir manuscript Go into the folder: {:lang=”sh”} $ cd manuscript 本文档使用 书栈(BookStack.CN) 构建 - 22 - 

23 .Leanpubbin’: A Brief Introduction To Leanpub Create a Book.txt file: {:lang=”sh”} $ touch Book.txt Now we add chapters to our index: 1. 001_Introduction.md and so on.. When formated as Markdown a Leanpub book looks like: {:lang=”md”} 1. # Chapter Title 2. 3. Chapter contents 4. 5. ## Section Title 6. 7. Section contents Leanpub Markdown flavor Leanpub Markdown is based on Kramdown. The main thing you need to know beyond Kramdown’s documentation is: 1. Use h1’s for chapter titles. 2. Use h2’s for section titles. The h1’s and h2’s will be parsed and turned into your Table of Contents, so it’s important you don’t utilize them for things other than chapter titles and section titles. Images in Leanpub All assets are linked relative to your manuscript folder. Images are placed in manuscript/images. Link to them using the normal Markdown image syntax. For example; 本文档使用 书栈(BookStack.CN) 构建 - 23 - 

24 .Leanpubbin’: A Brief Introduction To Leanpub {:lang=”md”} They need to be at 300ppi if you intend to distribute you book via print. They will be upscaled to 300ppi automatically so if you intend to distribute entirely through digital means you can forgo creating them at 300ppi. It might be a good idea to create them at 300ppi anyway just to keep your options open. If you need your images in 300ppi (e.g after taking a screenshot) the easiest thing to do is run an imagemagick command against it: {:lang=”sh”} $ convert -units PixelsPerInch image -density 300 outimage Setting the density will be adequate if all you intend to do is distribute your book digitally. If you do print you’ll have to make sure to take them at retina resolutions and then do some post re-sampling. Something like: {:lang=”sh”} $ convert -units PixelsPerInch image -resample 300 outimage You can pass attributes like width and height they will be reflected in the final output. For example: {:lang=”md”} {width=60%,float=left} 1.  I> See the how-to-insert-an-image part of the Leanpub manual I> for more details. However, I recommend you don’t take advantage of Leanpub’s image attributes. They are not parsed like Kramdown’s and their syntaxes are incompatible. If you use Leanpub’s syntax will result in stray text (e.g {width=60%} _ appearing when you use Kramdown to generate PDFs. The best solution, is to simply not rely on image attributes. If you absolutely need image control in the final published PDF then use 本文档使用 书栈(BookStack.CN) 构建 - 24 - 

25 .Leanpubbin’: A Brief Introduction To Leanpub attribute lists, which are compatible with Kramdown. The Kramdown syntax looks like this: {:lang=”md”} {:width=100%} Previewing Leanpub locally Previewing is central to a Leanpub workflow, you’ll be doing it a lot. So much, that manually previewing is likely to get cumbersome. To keep your sanity you are going to need a variety of methods to quickly preview changes. Methods that don’t require you to wait for Leanpub to process your book. T> Previews from Leanpub will be generated into your Dropbox folder in /Preview. You can manually edit these if you T> want to get clever but I highly recommend you only use them for previewing. Previewing with Sublime Thankfully someone has built an extension for this called sublimetext- markdown-preview. We can install it using Package Manger; 1. Shift + CRTL + P. 2. Install Package: Markdown Preview. Once you have it installed you can just hit CRTL + SHFIT + P (P is for preview) and a browser window will open with a preview. Previewing with VIM There are a few scripts for this. Here is one Previewing with Guard and HTML A good cross-platform, cross-editor, solution, is to monitor your Markdown files and generate HTML when they change, 本文档使用 书栈(BookStack.CN) 构建 - 25 - 

26 .Leanpubbin’: A Brief Introduction To Leanpub then you can just use your browser to preview the result. This solution has the added benefit of allowing us to generate previews using Kramdown, which means our previews will support everything Leanpub does. To do this we will use guard and a guard script that monitors Markdown files. First we have to install Guard. The process is fairly simple: {:lang=”sh”} $ gem install guard A> Add sudo if installing to system. Drop the sudo on Mac. Also drop sudo when using rbenv. On windows, drop A> everything, run around screaming, then install a decent Operating System. In your ebook folder run: {:lang=”sh”} $ guard init Now install the markdown monitor: {:lang=”sh”} $ gem install guard-markdown Add an example guard for Markdown to your Guardfile by running: {:lang=”sh”} $ guard init markdown It will generate something like this: {:lang=”ruby”} guard ‘markdown’, :convert_on_start => true, :dry_run => true do watch (/source_dir\/(.+\/)*(.+.)(md|markdown)/i) { |m| “source_dir/# {m[1]}#{m[2]}#{m[3]}|output_dir/#{m[1]}#{m[2]}html”} end We want to change the source dir to `/manuscript, set the output_dir, and enable it: {:lang=”ruby”} guard ‘markdown’, :convert_on_start => true do 本文档使用 书栈(BookStack.CN) 构建 - 26 - 

27 .Leanpubbin’: A Brief Introduction To Leanpub watch (/manuscript\/(.+\/)*(.+.)(md|markdown)/i) { |m| “manuscript/# {m[1]}#{m[2]}#{m[3]}|preview_html/#{m[1]}#{m[2]}html”} end Launch it with: {:lang=”sh”} $ guard A> Run this in the ebook’s folder Now we need to make sure our browser gets reloaded when the files change. We can do this with guard-livereload and a LiveReload browser extension. Once you have the relevant browser extension installed do the following: {:lang=”sh”} $ gem install guard-livereload Then add the following to your Guardfile: {:lang=”ruby”} guard ‘livereload’ do watch(%r{preview_html/.+.(html)}) end T> You might want to add preview_html to your .gitignore file as well. Other Preview Apps For Mac I recommend MouApp. For Linux there is ReText Remember to follow the golden rule of Keeping it Simple. Your Markdown productivity shouldn’t be tied to any specific app. Choose things that complement your workflow not supplement it. 本文档使用 书栈(BookStack.CN) 构建 - 27 - 

28 .LaTeXing LaTeXing LaTeXing Installing LaTeX On Mac On Ubuntu (and other Debians) Installing LaTeX Packages on Mac Installing LaTeX Packages on Ubuntu (and other Debians) Using Packages LaTeX: A Very Brief Introduction Custom LaTeX Styles LaTeXing It’s no good being tied completely to Leanpub for publishing. Eventually we will want someway to locally generate all the formats that Leanpub does. We have already covered generating HTML locally, but what about PDFs? Kramdown doesn’t support PDFs natively, it uses an in-between format called LaTeX. So before we get started on converting Markdown to PDFs we are going to have to learn some LaTeX. LaTeX knowledge is not strictly necessary but it’s going to be beneficial to know how the magic works. Magic is great and makes things easier, but when it fails, and you don’t know how it works, frustration finds its way into your soul. Frustration kills the desire to create and will leave you a sad, bleeding, heaving mess on the floor. Probably not that graphic, but it’s terrible, trust me. Let’s avoid some future frustration and learn a little LaTeX. Installing LaTeX Before you dive in there are some things you need to know. The LaTeX community is a bit bloated. Well, maybe “a bit” is an understatement, LaTeX makes Photoshop seem like an anorexic. This bloat is the result of the community being really old in software years — TeX is older than I am. As a result of its 本文档使用 书栈(BookStack.CN) 构建 - 28 - 

29 .LaTeXing age, LaTeX has accumulated a ton of stuff. LaTeX standard distributions are measured in the gigabytes! It has more GUIs than a Windows development community, more packages than a Ruby community and an outdated package distribution model that makes Macports seem like homebrew. TeX is what happens when an emacs-esque community spends its time writing technical papers and doesn’t have VIM fights to keep them busy. Bloat in distributions alone wouldn’t be so bad but the documentation is bloated as well. Want to add code highlighting? There are a million different solutions and a million different suggestions. Want a GUI for previewing? Pick one of dozens. Want an implementation that is more turing complete? Do you want your turing in LaTeX, Lua, or Ruby? I’m going to simplify things and tell you what to use. You don’t have to ultimately follow my suggestions, but stick with them until you figure out what you’re doing. Fight the urge to over evaluate and pick the best solutions. Without knowledge you won’t be able to evaluate anything. Choosing from a place of ignorance is an exercise in futility. You’ll find that by diving in, you’ll discover what you like — what your taste in tools is; you’ll ultimately discover what works for you. On Mac As much as I’d like to recommend you use a package manager like homebrew or macprots to keep TeX up to date, it’s not a good idea. Unfortunately, using homebrew would cause more problems with bugs and compatibility issues than you’d gain from using it. The best way (and the official way) is to install LaTeX + TeX from mactex.org. Just follow the instructions and you should be good to go. On Ubuntu (and other Debians) Installing LaTeX on Ubuntu is pretty straightforward and essentially involves running the following: 本文档使用 书栈(BookStack.CN) 构建 - 29 -