[{"_1":2,"_161":-5,"_162":-5},"loaderData",{"_3":4,"_17":18,"_25":26,"_140":141},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","routes/_layout",{"_19":-5,"_20":21,"_22":21,"_23":11,"_24":21},"username","isAskGordonEnabled",true,"isUsingNewTemplate","showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":-5,"_89":90,"_128":-5,"_129":11,"_130":21,"_131":11,"_132":11,"_133":-5,"_134":11,"_135":-5,"_136":137,"_138":91,"_139":-7},"canonicalUrl","https://hub.docker.com/r/bclapper/ebook-template/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","bclapper","reponame","ebook-template","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":11,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2019-01-19T20:38:54.566687Z","description","","is_private","last_updated","2019-03-09T03:49:14.851197Z","last_modified","2024-10-16T13:48:34.145251Z","media_types",[56],"application/vnd.docker.container.image.v1+json","name","pull_count",1367,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","# ebook-template\n\n## Overview\n\nThis repository is a template for a project that'll build an eBook (in\nePub, PDF, Microsoft Word and HTML form) from Markdown input files.\n\ntl;dr: You write your book as a series of Markdown files, adhering to some\n[file naming conventions](#book-source-file-names), and you run the `./build`\ncommand (see [Building your book](#building-your-book)) to build your book.\n\nThere are sample files in this repository, so you can build a (completely\npointless and utterly useless) eBook right away.\n\nThis tooling has been tested with [Pandoc][] versions 2.0.4 and 2.0.5.\n\nIf you're impatient, jump to [Getting Started](#getting-started).\n\n## What's where\n\n- Your book's Markdown sources, cover image, and some metadata go in the\n `book` subdirectory. This is where you'll be doing your editing.\n\n- The `files` subdirectory contains files used by the build. For instance, the\n HTML and ePub style sheets are there, as are LaTeX templates (used for PDF\n output) and a Microsoft Word style reference document. You shouldn't need to\n touch anything in `files`.\n\n- The `scripts` subdirectory currently just contains a Pandoc filter used to\n provide [enhanced markup](#additional-markup). You shouldn't need to touch\n anything in `scripts`.\n\n- The `lib` directory contains some additional Python code used by the build.\n Ignore it.\n\n- Your book output files (`book.docx`, `book.epub`, `book.pdf` and\n `book.html`) are generated in the topmost directory.\n\n- The build will also generate a subdirectory called `tmp` to hold some\n temporary files. Git is configured to ignore that directory.\n\n## Supported output formats\n\nThis tooling will generate your book in the following formats:\n\n### ePub\n\n`book.epub`\n\nePub is the format used by Apple's iBooks and various free readers, including\n[Calibre][].\n\n### PDF\n \n`book.pdf` is a single PDF document, generated by LaTeX or [Weasy Print][].\n\n**Issues**:\n\n- LaTeX PDF generation uses the LaTeX \"article\" document class, rather than the\n seemingly more suitable \"book\" class, because the \"book\" class, combined\n with Pandoc's LaTeX generation, is just a little too funky.\n- Weasy Print-generated PDF has no table of contents.\n\n### HTML\n\n`book.html` is a single-page HTML, styled in a pleasant format.\n\n### Microsoft Word\n\n`book.docx` is a Microsoft Word version of your book.\n\n**Issues:**\n\n- There's no table of contents.\n- The cover image is not included in the Word document.\n\n## Unsupported formats\n\n### Kindle (MOBI)\n\nPandoc can't generate books in Kindle format. However, there are several\noptions for generating Kindle content:\n \n- Haul the Microsoft Word version into \n [Kindle Create](https://kdp.amazon.com/en_US/help/topic/G202131100)\n\n- Use the free and open source [Calibre][] suite to convert the ePub format to\n Kindle format.\n\n## Getting started\n\nStart by downloading and unpacking the latest\n[release](https://github.com/bmc/ebook-template/releases) of this repository.\n(By downloading a release, instead of cloning the repository, you can more\neasily create your own Git repository from the results.)\n\nThen, install the required software and update the configuration files.\n\n**Note**: If you use the Docker approach, you won't have to worry about \ninstalling the [required software](#required-software).\n\n### Using Docker\n\nIf you don't want to install the dependencies on your machine, you can pull\na Docker image that has everything you need. In the top-level directory,\nthere's a `./build-docker` script you can use, instead of the `./build`\nscript. Where `./build` assumes you have all the prerequisite software on your\nmachine, `./build-docker` pulls down a prebuilt Docker image containing\neverything you need, then uses that image to build your ebook.\n\nWhen you run `./build-docker`, the script will:\n\n- pull the latest Docker image from `bclapper/ebook-template` (on Docker Hub)\n- fire up an instance of the image, making the current working directory\n available to Docker, and\n- run `./build` within the image.\n\nThe Docker image contains all the required software, so you don't have to\ninstall anything (except, of course, Docker).\n\n\n### Upgrading\n\nIf you're already using this tooling for one of your books, and you want to\nupgrade to a newer version, the process (currently) is straightforward:\n\n- Download and unpack the new version, as described above. Don't unpack it\n over your project!\n- Run the new version's `upgrade.py` file from your project's top level\n directory.\n- Run `./upgrade.py` from within your project, passing it the path to the\n unpacked new release.\n\nFor example:\n\n```\ncd /tmp\ntar xf /path/to/downloaded/ebook-template-X.Y.Z.tgz\ncd /path/to/your/ebook\n/tmp/ebook-template-X.Y.Z/upgrade.py /tmp/ebook-template-X.Y.Z\n```\n\nNote that this copies files, removing ones that aren't necessary any more.\nIf there are metadata changes, however, `upgrade.py` won't apply them.\nBe sure to read the change log for the new release.\n\n### Required software\n\nIf you're not using Docker, you'll need to install a bunch of tools on your\nlocal machine.\n\n1. Install [pandoc](http://pandoc.org/installing.html).\n2. Install a Python distribution, version 3.6 or better.\n * On Mac OS, `brew install python3` will suffice.\n * On Ubuntu/Debian,\n [this article](https://unix.stackexchange.com/questions/332641/how-to-install-python-3-6)\n might help.\n * On Windows, see .\n3. I recommend creating and activating a\n [Python virtual environment](https://virtualenv.pypa.io/en/stable/),\n to keep the installed version of Python 3 more or less pristine.\n4. Once you have your Python 3 environment set up (and activated, if you're\n using a virtual environment), install the required Python packages with\n `pip install -r requirements.txt`\n5. You can generate PDF via either LaTeX or [Weasy Print][]. There are\n advantages and disadvantages to each; see [Generating PDF](#generating-pdf),\n below.\n * If you'll be using LaTeX, install a TexLive distribution, as detailed\n [below](installing-texlive).\n * If you'll be using [Weasy Print][], make sure your Python 3 environment\n is activated, and follow the directions at \n \n\n#### Installing TexLive\n\n* On Mac OS, use [MacTex](https://www.tug.org/mactex/mactex-download.html),\n and ensure that `/Library/TeX/texbin` is in your path.\n* On Ubuntu/Debian, install `texlive`, `texlive-latex-recommended` and\n `texlive-latex-extras`.\n* On Windows, this might work: .\n\n**WARNING**: I avoid Windows as much as possible. I do not (and, likely,\nnever will) test this stuff on Windows. If you insist on using that platform,\nyou're more or less on your own. (I recommend using the Docker approach on\nWindows.)\n\n### Initial configuration\n\n#### Create your cover image\n\nIn your `book` directory, create a cover image, as a PNG. If you haven't\nsettled on a cover image yet, you can use the dummy image that's already\nthere. **Currently, the cover image is not optional.**\n\n#### Fill in the metadata\n\nEdit `book/metadata.yaml`, and fill in the relevant pieces. Both Pandoc\nand the build tooling use this metadata.\n\n**Note**: This file contains \n[Pandoc YAML Metadata](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block),\nwith some additional fields used by this build tooling.\n\nThe following elements are _required_.\n\n- `title` (**Required**): The book title.\n\n- `subtitle` (**Optional**): Subtitle, if any.\n\n- `author` (**Required**): A YAML list of authors. If there is only one author, use a \n single-element YAML list. For example:\n \n```yaml\nauthor:\n- Joe Horrid\n```\n\n```yaml\nauthor:\n- Joe Horrid\n- Frances Horrid\n```\n\n- `copyright` (**Required**): A block with two required fields, `owner` and\n `year`. See the existing sample `metadata.yaml` for an example.\n \n- `publisher` (**Required**): The publisher of the book.\n\n- `language` (**Required**): The language in which the book is written. The\n value can be a 2-letter [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639) \n code, such as \"en\" or \"fr\". It can also be a 2-part string consisting\n of the ISO 639-1 language code and the 2-letter\n [ISO 3166](https://docs.oracle.com/cd/E13214_01/wli/docs92/xref/xqisocodes.html)\n country code, such as \"en-US\", \"en-UK\", \"fr-CA\", \"fr-FR\", etc.\n\n- `genre` (**Required**): The book's genre. See\n for a list of genres.\n\n#### Edit the copyright information\n\nEdit the `book/copyright.md` file. You can leave `%` tokens in there; they'll\nbe substituted as described, below, in [Additional markup](#additional-markup).\nThe meaning of the `{<}` is also explained in that section.\n\n## Markup notes\n\nYour book will use Markdown, as interpreted by Pandoc. The following Pandoc\nextensions are enabled. See the\n[Pandoc User's Guide][] for full details.\n\n- `line_blocks`: Use vertical bars to create lines that are formatted as is.\n See for details.\n\n- `escaped_line_breaks`: A backslash followed by a newline is also a hard\n line break.\n See for details.\n\n- `yaml_metadata_block`: Allows metadata in the Markdown. See\n See for details.\n\n- `smart`: Interprets straight quotes as curly quotes, \"---\" as em-dashes, \n \"--\" as en-dashes, and \"...\" as ellipses. Nonbreaking spaces are inserted \n after certain abbreviations, such as \"Mr.\". See\n for details.\n \n- `backtick_code_blocks`, `fenced_code_blocks` and `fenced_code_attributes`: \n Allows fenced code blocks, using backticks (GitHub Flavored Markdown-style) \n and tildes (`~~~`). You can also supply attributes (classes, for instance). \n See ,\n and \n for details.\n\n\n### Additional markup\n\nThe build tool uses a [Pandoc filter](https://github.com/jgm/pandocfilters)\n(in `scripts/pandoc-filter.py`) to enrich the Markdown slightly:\n\n1. Level 1 headings denote new chapters and force a new page.\n2. If you want to force a new page without starting a new chapter, just\n include an empty level-1 header (`#`). See `book/copyright-template.md` \n for an example.\n3. A paragraph containing just the line `+++` is replaced by a centered line\n containing \"• • •\". This is a useful separator.\n4. A paragraph that starts with `{<}` followed by at least one space is\n left-justified. See `book/copyright-template.md` for an example.\n5. A paragraph that starts with `{>}` followed by at least one space is\n right-justified.\n6. A paragraph that starts with `{|}` followed by at least one space is\n centered.\n\nNote, too, that Pandoc automatically converts your quotation marks into\nsmart quotes, triple dots (`...`) into an ellipsis, and two dashes (`--`)\ninto an em-dash.\n\n(The filter is written in Python, using the\n[Panflute](http://scorreia.com/software/panflute/) package.)\n\n### Support for PlantUML\n\nIf you set `use_plantuml` to `true` in your metadata, you can use \n[PlantUML](http://plantuml.com/) diagrams in your book, using special\nfenced code blocks. For instance:\n\n```\n~~~plantuml\n@startuml\nclient->server: SYN\nserver->client: SYN+ACK\nclient->server: ACK\n@enduml\n~~~\n```\n\nYou can use either tildes or backticks, and you can also use Pandoc-style\nfenced code blocks to supply attributes. If you specify an \"alt\" attribute\nor a \"title\" attribute, it will be used as the title for the image (for\nreaders that display the title). If you specify both, \"title\" is preferred.\nFor example:\n\n```\n~~~ {.plantuml title=\"4-way handshake\"}\n@startuml\nclient->server: FIN\nserver->client: ACK\nserver->client: FIN\nclient->server: ACK\n@enduml\n~~~\n```\n\nChapter 1 of the sample book contains these two examples.\n\n\n## Book source file names\n\nThe tooling expects your book's Markdown sources to be in the `book`\nsubdirectory and to adhere to the following conventions:\n\n- All files must have the extension `.md`.\n\n- If you create a file called `dedication.md`, it'll be placed right after the\n copyright page in the generated output. See `dedication.md` for an example.\n If you don't want a dedication, simply delete the provided `dedication.md`.\n\n- If your book has a foreward, just create file `foreward.md`, and it'll\n be inserted right after the dedication. Otherwise, just delete the supplied\n sample `foreward.md`.\n\n- If your book has a preface, just create file `preface.md`, and it'll\n be inserted right after the foreward. Otherwise, just delete the supplied\n sample `preface.md`.\n\n- If the book has a prologue, put it in file `prologue.md`. It'll appear\n before the first chapter. If you don't want a prologue, simply delete the\n provided `prologue.md`.\n\n- Keep each chapter in a separate file. (This is easier for editing, source\n control, etc.) Name the files `chapter-NN.md`. For instance,\n `chapter-01.md`, `chapter-02.md`, etc. The chapter files are sorted\n lexically, so the leading zeros are necessary if you have more than 9\n chapters. If you have more than 100 chapters (_seriously?_), just add\n another leading zero (e.g., `chapter-001.md`). If you _must_ put the entire\n content in one file, the file's name must start with `chapter-` and end in\n `.md`.\n \n- If the book has an epilogue, put it in file `epilogue.md`. It'll follow the\n last chapter. If you don't want an epilogue, simply delete the provided\n `epilogue.md`.\n\n- If you create a file called `acknowledgments.md`, it'll be placed after the\n epilogue. If you don't want an acknowledgements chapter, simply delete the\n provided `acknowledgments.md`.\n\n- If you need one or more appendices, just create files that start with\n `appendix-` and end with `.md`. Note that the files are sorted lexically.\n There are sample appendix files in `book`; delete them if you don't want\n any appendices.\n\n- If you plan to provide a glossary, create `glossary.md`. If you don't need\n a glossary, delete the provided sample file.\n\n- If you want to include an author biography, just create `author.md`.\n\n- If you need a references (bibliography) section, create `references.yaml`,\n as described below. If you don't need a bibliography section, just delete\n the provided sample `references.yaml`.\n \n**NOTE**: There's currently no support for generating an index.\n\n### Summary of chapter ordering\n\n- title page\n- dedication (if present)\n- foreward (if present)\n- preface (if present)\n- prologue (if present)\n- all chapters\n- epilogue (if present)\n- acknowledgments (if present)\n- appendices (if present)\n- glossary (if present)\n- author (if present)\n- references (if present)\n\n### Generating PDF\n\nYou can generate PDF via either LaTeX or [Weasy Print][].\n\n| PDF engine | Advantages | Disadvantages\n| ----------- | ---------- | -------------\n| LaTeX | rich typesetting, table of contents | LaTeX fonts aren't supported by all printers\n| Weasy Print | good printer font support | no table of contents \n\n### Images\n\nImage references to files are relative to the _top_ directory, not to the\n`book` directory. It's best to stick with PNG images.\n\n### Table of contents\n\n- **PDF**: If you're using LaTeX, Pandoc automatically generates the table of \n contents in the PDF. If you're using Weasy Print, there's no table of \n contents.\n\n- **ePub**: Pandoc generates the table of contents as part of the ePub package.\n\n- **HTML**: The build tool includes JavaScript that generates a table\n of contents in the browser.\n\n- **Word**: Pandoc doesn't generate a table of contents for Microsoft Word,\n because it's trivial to create your own. In newer versions of Microsoft\n Word (e.g., the version you get with Office 365):\n - Insert a page break to create a new, blank page.\n - Select \"References\" from the menu bar.\n - Select \"Table of Contents\", and select your desired style.\n \n### Bibliographic references\n\nIf you're writing a book that needs a bibliography _and_ uses citations in\nthe text, there's a bit of extra work.\n\nFirst, install [`pandoc-citeproc`](https://github.com/jgm/pandoc-citeproc).\n\n- On Mac OS, use `brew install pandoc-citeproc`.\n- On Ubuntu/Debian, it should have been installed when you installed `pandoc`.\n- On Windows, it should have been installed when you installed `pandoc`.\n\nNext, you'll need to create the bibliography YAML file,\n`book/references.yaml`, suitably organized for `pandoc` to consume. The sample\n`book/references.yaml` contains a single entry. You can hand-code this file,\nor you can use `pandoc-citeproc` to generate it from an existing bibliographic\nfile (e.g., a BibTeX file).\n\nSee the [citations section][] in the Pandoc User's Guide and the\n[`pandoc-citeproc` man page](https://github.com/jgm/pandoc-citeproc/blob/master/man/pandoc-citeproc.1.md)\nfor more details.\n\n**NOTE**: The presence of a `book/references.yaml` file triggers the build\ntooling to include a **References** chapter, to which `pandoc` will add any\ncited works. Your bibliography (`book/references.yaml`) can contain as many\nreferences as you want; only the ones you actually cite in your text will show\nup in the References section. If your text contains no citations, the\nReferences section will be empty. The build tooling does _not_ check first to\nsee whether you actually have any citations in your text.\n\nAn example of a citation is:\n\n```\n[See @WatsonCrick1953]\n```\n\nAgain, see the [citations section][] of the [Pandoc User's Guide][] for\nfull details.\n\n## Styling your book\n\nThe ePub styling uses `files/epub.css`, and the HTML is styled with\n`files/html.css`.\n\nYou can change the styling by providing your own version of those files\nin the `book` directory. That is:\n\n- If `book/html.css` exists, it will be used instead of `files/html.css`.\n- If `book/epub.css` exists, it will be used instead of `files/epub.css`.\n\n## Building your book\n\nOnce you've prepared everything, as described above, you can rebuild the\nbook by running the command:\n\n```\n./build\n```\n\n`./build` is a Python script using the Python [doit](http://pydoit.org/)\nbuild tool. You should not need to edit it; editing `metadata.yaml` is\nsufficient to specify the information about your book.\n\n### Other useful build targets\n\n- `./build version`: Show what version of this tooling you have.\n- `./build docx`: Build just the Microsoft Word version of the book.\n- `./build pdf`: Build just the PDF version of the book.\n- `./build epub`: Build just the ePub version of the book.\n- `./build html`: Build just the HTML version of the book.\n\nYou can combine targets:\n\n```\n./build docx pdf\n```\n\n### Cleaning up generated files\n\nTo clean up the built targets:\n\n```\n./build clean\n```\n\nTo clean _everything_ out (except `doit-db.json`, which won't go away):\n\n```\n./build clobber\n```\n\n### Auto-building\n\nBecause `./build` is a [doit][] script, it supports _auto-building_. If you\nrun it as follows:\n\n```\n./build auto\n```\n\nit will build your book (if it's not up-to-date), then wait; any time one or\nmore of the source Markdown files changes, it will automatically rebuild your\nbook. To stop it, just hit Ctrl-C.\n\n**NOTE**: Auto-building will _not_ detect the addition of new files. For\ninstance, if you're running in auto-build mode, and you add a new\n`chapter-03.md` file, the build script will _not_ detect it. You'll have to\nkill the auto-build and restart it.\n\n### Gotchas\n\nBut that doesn't _always_ work as expected. For instance, from traditional\n_make_(1) usage, you might expect `build clean pdf` to run the \"clean\" target,\n_then_ run the \"pdf\" target. Instead, it _just_ runs the \"clean\" operation for\nthe PDF. (That's a [doit][] quirk.)\n\n## Copyright and License\n\nThis software is copyright © 2017 Brian M. Clapper and is released under the\n[GPL, version 3][], similar to the license the underlying [Pandoc][] software\nuses. See the [LICENSE](LICENSE.md) for further details.\n\n[GPL, version 3]: http://www.gnu.org/copyleft/gpl.html\n[citations section]: http://pandoc.org/MANUAL.html#extension-citations\n[Pandoc]: http://pandoc.org\n[Pandoc User's Guide]: http://pandoc.org/MANUAL.html\n[doit]: http://pydoit.org/\n[Calibre]: https://www.calibre-ebook.com/\n[Weasy Print]: http://weasyprint.org\n\n","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":21,"_83":11,"_84":11},"read","write","admin","user","storage_size",807496806,"orgData","recentTags",[91],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_50":117,"_118":94,"_119":33,"_120":56,"_57":121,"_122":123,"_124":108,"_125":117,"_126":66,"_127":21},"content_type","creator",3840937,"full_size",432574679,"id",44602356,"images",[101],{"_102":103,"_104":105,"_106":48,"_107":108,"_109":110,"_111":112,"_113":48,"_114":-5,"_115":96,"_63":66,"_116":-5},"architecture","amd64","digest","sha256:05ef01f2400bf9443c72f2b468a22fba2471f24210ce48da8a48e314d13cc10f","features","last_pulled","2026-10-18T04:08:27.953499388Z","last_pushed","2019-03-07T17:09:30Z","os","linux","os_features","os_version","size","variant","2019-03-09T03:49:14.504255Z","last_updater","last_updater_username","media_type","latest","repository",6572217,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxRunInCloud","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":142,"_149":150,"_136":159,"_160":11},{"_40":143,"_42":144,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":145,"_57":35,"_32":33,"_58":59,"_60":44,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":146,"_79":11,"_80":148,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":147},[78],{"_82":21,"_83":11,"_84":11},"tags",{"_151":64,"_152":-5,"_153":-5,"_154":155},"count","next","previous","results",[156],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":157,"_50":117,"_118":94,"_119":33,"_120":56,"_57":121,"_122":123,"_124":108,"_125":117,"_126":66,"_127":21},[158],{"_102":103,"_104":105,"_106":48,"_107":108,"_109":110,"_111":112,"_113":48,"_114":-5,"_115":96,"_63":66,"_116":-5},[],"canDeleteTags","actionData","errors"]

bclapper/ebook-template

Tags for bclapper/ebook-template