{"id":13760255,"url":"https://github.com/wikiti/pandoc-book-template","last_synced_at":"2025-05-10T10:32:04.963Z","repository":{"id":43642679,"uuid":"79052338","full_name":"wikiti/pandoc-book-template","owner":"wikiti","description":"A simple Pandoc template to build documents and ebooks.","archived":false,"fork":false,"pushed_at":"2024-05-27T20:17:16.000Z","size":80,"stargazers_count":385,"open_issues_count":2,"forks_count":88,"subscribers_count":12,"default_branch":"master","last_synced_at":"2024-08-03T13:04:31.371Z","etag":null,"topics":["ebook","epub","html","markdown","pandoc","pdf","template"],"latest_commit_sha":null,"homepage":"","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wikiti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-15T18:51:40.000Z","updated_at":"2024-08-03T13:04:34.317Z","dependencies_parsed_at":"2024-08-03T13:14:32.750Z","dependency_job_id":null,"html_url":"https://github.com/wikiti/pandoc-book-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikiti%2Fpandoc-book-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikiti%2Fpandoc-book-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikiti%2Fpandoc-book-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wikiti%2Fpandoc-book-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wikiti","download_url":"https://codeload.github.com/wikiti/pandoc-book-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224949743,"owners_count":17397230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebook","epub","html","markdown","pandoc","pdf","template"],"created_at":"2024-08-03T13:01:06.122Z","updated_at":"2024-11-16T17:30:52.662Z","avatar_url":"https://github.com/wikiti.png","language":"CSS","funding_links":[],"categories":["CSS"],"sub_categories":[],"readme":"# Pandoc book template\n\n[![CircleCI](https://circleci.com/gh/wikiti/pandoc-book-template.svg?style=shield)](https://circleci.com/gh/wikiti/pandoc-book-template)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/wikiti/pandoc-book-template/blob/master/LICENSE.md)\n\n## Description\n\nThis repository contains a simple template for building [Pandoc](http://pandoc.org/) documents;\nPandoc is a suite of tools to compile markdown files into readable files (PDF, EPUB, HTML...).\n\n## Usage\n\n### Installing\n\nPlease, check [this page](http://pandoc.org/installing.html) for more information. On ubuntu, it\ncan be installed as the *pandoc* package:\n\n```sh\nsudo apt-get install pandoc\n```\n\nThis template uses [make](https://www.gnu.org/software/make/) to build the output files, so don't\nforget to install it too:\n\n```sh\nsudo apt-get install make\n```\n\nTo export to PDF files, make sure to install the following packages:\n\n```sh\nsudo apt-get install texlive-fonts-recommended texlive-xetex\n```\n\n### Folder structure\n\nHere's a folder structure for a Pandoc book:\n\n```\nmy-book/         # Root directory.\n|- build/        # Folder used to store builded (output) files.\n|- chapters/     # Markdowns files; one for each chapter.\n|- images/       # Images folder.\n|  |- cover.png  # Cover page for epub.\n|- metadata.yml  # Metadata content (title, author...).\n|- Makefile      # Makefile used for building our books.\n```\n\n### Setup generic data\n\nEdit the *metadata.yml* file to set configuration data (note that it must start and end with `---`):\n\n```yml\n---\ntitle: My book title\nauthor: Daniel Herzog\nrights: MIT License\nlang: en-US\ntags: [pandoc, book, my-book, etc]\nabstract: |\n  Your summary.\nmainfont: DejaVu Sans\n\n# Filter preferences:\n# - pandoc-crossref\nlinkReferences: true\n---\n```\n\nYou can find the list of all available keys on\n[this page](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block).\n\n### Creating chapters\n\nCreating a new chapter is as simple as creating a new markdown file in the *chapters/* folder;\nyou'll end up with something like this:\n\n```\nchapters/01-introduction.md\nchapters/02-installation.md\nchapters/03-usage.md\nchapters/04-references.md\n```\n\nPandoc and Make will join them automatically ordered by name; that's why the numeric prefixes are\nbeing used.\n\nAll you need to specify for each chapter at least one title:\n\n```md\n# Introduction\n\nThis is the first paragraph of the introduction chapter.\n\n## First\n\nThis is the first subsection.\n\n## Second\n\nThis is the second subsection.\n```\n\nEach title (*#*) will represent a chapter, while each subtitle (*##*) will represent a chapter's\nsection. You can use as many levels of sections as markdown supports.\n\n#### Manual control over page ordering\n\nYou may prefer to have manual control over page ordering instead of using numeric prefixes.\n\nTo do so, replace `CHAPTERS = chapters/*.md` in the Makefile with your own order. For example:\n\n```\nCHAPTERS += $(addprefix ./chapters/,\\\n 01-introduction.md\\\n 02-installation.md\\\n 03-usage.md\\\n 04-references.md\\\n)\n```\n\n#### Links between chapters\n\nAnchor links can be used to link chapters within the book:\n\n```md\n// chapters/01-introduction.md\n# Introduction\n\nFor more information, check the [Usage] chapter.\n\n// chapters/02-installation.md\n# Usage\n\n...\n```\n\nIf you want to rename the reference, use this syntax:\n\n```md\nFor more information, check [this](#usage) chapter.\n```\n\nAnchor names should be downcased, and spaces, colons, semicolons... should be replaced with hyphens.\nInstead of `Chapter title: A new era`, you have: `#chapter-title-a-new-era`.\n\n#### Links between sections\n\nIt's the same as anchor links:\n\n```md\n# Introduction\n\n## First\n\nFor more information, check the [Second] section.\n\n## Second\n\n...\n```\n\nOr, with al alternative name:\n\n```md\nFor more information, check [this](#second) section.\n```\n\n### Inserting objects\n\nText. That's cool. What about images and tables?\n\n#### Insert an image\n\nUse Markdown syntax to insert an image with a caption:\n\n```md\n![A cool seagull.](images/seagull.png)\n```\n\nPandoc will automatically convert the image into a figure, using the title (the text between the\nbrackets) as a caption.\n\nIf you want to resize the image, you may use this syntax, available since Pandoc 1.16:\n\n```md\n![A cool seagull.](images/seagull.png){ width=50% height=50% }\n```\n\n#### Insert a table\n\nUse markdown table, and use the `Table: \u003cYour table description\u003e` syntax to add a caption:\n\n```md\n| Index | Name |\n| ----- | ---- |\n| 0     | AAA  |\n| 1     | BBB  |\n| ...   | ...  |\n\nTable: This is an example table.\n```\n\n#### Insert an equation\n\nWrap a LaTeX math equation between `$` delimiters for inline (tiny) formulas:\n\n```md\nThis, $\\mu = \\sum_{i=0}^{N} \\frac{x_i}{N}$, the mean equation, ...\n```\n\nPandoc will transform them automatically into images using online services.\n\nIf you want to center the equation instead of inlining it, use double `$$` delimiters:\n\n```md\n$$\\mu = \\sum_{i=0}^{N} \\frac{x_i}{N}$$\n```\n\n[Here](https://www.codecogs.com/latex/eqneditor.php)'s an online equation editor.\n\n#### Cross references\n\nOriginally, this template used LaTeX labels for auto numbering on images, tables, equations or\nsections, like this:\n\n```md\nPlease, admire the gloriousnes of Figure \\ref{seagull_image}.\n\n![A cool seagull.\\label{seagull_image}](images/seagull.png)\n```\n\n**However, these references only works when exporting to a LaTeX-based format (i.e. PDF, LaTeX).**\n\nIn case you need cross references support on other formats, this template now support cross\nreferences using [Pandoc filters](https://pandoc.org/filters.html). If you want to use them, use a\nvalid plugin and with its own syntax.\n\nUsing [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) is highly recommended, but\nthere are other alternatives which use a similar syntax, like\n[pandoc-xnos](https://github.com/tomduck/pandoc-xnos).\n\nFirst, enable the filter on the *Makefile* by updating the `FILTER_ARGS` variable with your new\nfilter(s):\n\n```make\nFILTER_ARGS = --filter pandoc-crossref\n```\n\nThen, you may use the filter cross references. For example, *pandoc-crossref*  uses\n`{#\u003ctype\u003e:\u003cid\u003e}` for definitions and `@\u003ctype\u003e:id` for referencing. Some examples:\n\n```md\nList of references:\n\n- Check @fig:seagull.\n- Check @tbl:table.\n- Check @eq:equation.\n\nList of elements to reference:\n\n![A cool seagull](images/seagull.png){#fig:seagull}\n\n$$ y = mx + b $$ {#eq:equation}\n\n| Index | Name |\n| ----- | ---- |\n| 0     | AAA  |\n| 1     | BBB  |\n| ...   | ...  |\n\nTable: This is an example table. {#tbl:table}\n```\n\nCheck the desired filter settings and usage for more information\n([pandoc-crossref usage](http://lierdakil.github.io/pandoc-crossref/)).\n\n#### Content filters\n\nIf you need to modify the MD content before passing it to pandoc, you may use `CONTENT_FILTERS`. By\nsetting this makefile variable, it will be passed to the markdown content before passing it to\npandoc. For example, to replace all occurrences of `@pagebreak` with\n`\u003cdiv style=\"page-break-before: always;\"\u003e\u003c/div\u003e` you may use a `sed` filter:\n\n```\nCONTENT_FILTERS = sed 's/@pagebreak/\"\u003cdiv style=\\\"page-break-before: always;\\\"\u003e\u003c\\/div\u003e\"/g'\n```\n\nTo use multiple filters, you may include multiple pipes on the `CONTENT_FILTERS` variable:\n\n```\nCONTENT_FILTERS = \\\n  sed 's/@pagebreak/\"\u003cdiv style=\\\"page-break-before: always;\\\"\u003e\u003c\\/div\u003e\"/g' | \\\n  sed 's/@image/[Cool image](\\/images\\/image.png)/g'\n```\n\n### Output\n\nThis template uses *Makefile* to automatize the building process. Instead of using the *pandoc cli\nutil*, we're going to use some *make* commands.\n\n#### Export to PDF\n\nPlease note that PDF file generation requires some extra dependencies (~ 800 MB):\n\n```sh\nsudo apt-get install texlive-xetex ttf-dejavu\n```\n\nAfter installing the dependencies, use this command:\n\n```sh\nmake pdf\n```\n\nThe generated file will be placed in *build/pdf*.\n\n#### Export to EPUB\n\nUse this command:\n\n```sh\nmake epub\n```\n\nThe generated file will be placed in *build/epub*.\n\n#### Export to HTML\n\nUse this command:\n\n```sh\nmake html\n```\n\nThe generated file(s) will be placed in *build/html*.\n\n#### Export to DOCX\n\nUse this command:\n\n```sh\nmake docx\n```\n\nThe generated file(s) will be placed in *build/docx*.\n\n#### Extra configuration\n\nIf you want to configure the output, you'll probably have to look the\n[Pandoc Manual](http://pandoc.org/MANUAL.html) for further information about pdf (LaTeX) generation,\ncustom styles, etc, and modify the Makefile file accordingly.\n\n#### Templates\n\nOutput files are generated using [pandoc templates](https://pandoc.org/MANUAL.html#templates). All\ntemplates are located under the `templates/` folder, and may be modified as you will. Some basic\nformat templates are already included on this repository, ion case you need something to start\nwith.\n\n## References\n\n- [Pandoc](http://pandoc.org/)\n- [Pandoc Manual](http://pandoc.org/MANUAL.html)\n- [Wikipedia: Markdown](http://wikipedia.org/wiki/Markdown)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikiti%2Fpandoc-book-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwikiti%2Fpandoc-book-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwikiti%2Fpandoc-book-template/lists"}