{"id":42212931,"url":"https://github.com/foliant-docs/foliantcontrib.pandoc","last_synced_at":"2026-01-27T01:06:56.789Z","repository":{"id":57431755,"uuid":"114204253","full_name":"foliant-docs/foliantcontrib.pandoc","owner":"foliant-docs","description":"Pandoc backend for Foliant","archived":false,"fork":false,"pushed_at":"2022-07-23T10:07:35.000Z","size":1226,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2024-08-08T15:19:38.666Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/foliant-docs.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-14T04:55:12.000Z","updated_at":"2022-02-09T21:04:07.000Z","dependencies_parsed_at":"2022-09-02T11:51:44.764Z","dependency_job_id":null,"html_url":"https://github.com/foliant-docs/foliantcontrib.pandoc","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/foliant-docs/foliantcontrib.pandoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.pandoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.pandoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.pandoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.pandoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foliant-docs","download_url":"https://codeload.github.com/foliant-docs/foliantcontrib.pandoc/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.pandoc/sbom","scorecard":{"id":406093,"data":{"date":"2025-08-11","repo":{"name":"github.com/foliant-docs/foliantcontrib.pandoc","commit":"700796b4e2a4177ed38a692d939d8177270f685a"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Code-Review","score":0,"reason":"Found 0/28 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'develop'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 3 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T21:17:51.413Z","repository_id":57431755,"created_at":"2025-08-18T21:17:51.413Z","updated_at":"2025-08-18T21:17:51.413Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28794644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-27T01:06:56.216Z","updated_at":"2026-01-27T01:06:56.768Z","avatar_url":"https://github.com/foliant-docs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![](https://img.shields.io/pypi/v/foliantcontrib.pandoc.svg)](https://pypi.org/project/foliantcontrib.pandoc/) [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.pandoc.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.pandoc)\n\n# Pandoc Backend for Foliant\n\n![PDF built with Foliant](https://raw.githubusercontent.com/foliant-docs/foliantcontrib.pandoc/master/img/pandoc.png)\n\n[Pandoc](http://pandoc.org/) is a Swiss-army knife document converter. It converts almost any format to any other format: md to pdf, rst to html, adoc to docx, and so on and so on.\n\nPandoc backend for Foliant adds `pdf`, `docx`, `odt`, `epub` and `tex` targets.\n\n\n## Installation\n\n```shell\n$ pip install foliantcontrib.pandoc\n```\n\nYou also need to install Pandoc and TeXLive distribution for your platform.\n\n## Usage\n\nBuild pdf:\n\n```shell\n$ foliant make pdf -p my-project\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking pdf with Pandoc... Done\n─────────────────────\nResult: My_Project-2020-12-04.pdf\n```\n\nBuild docx:\n\n```shell\n$ foliant make docx -p my-project\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking docx with Pandoc... Done\n─────────────────────\nResult: My_Project-2020-12-04.docx\n```\n\nBuild odt:\n\n```shell\n$ foliant make odt -p my-project\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking odt with Pandoc... Done\n─────────────────────\nResult: My_Project-2020-12-04.odt\n```\n\nBuild epub:\n\n```shell\n$ foliant make epub -p my-project\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking epub with Pandoc... Done\n─────────────────────\nResult: My_Project-2020-12-04.epub\n```\n\nBuild tex (mostly for pdf debugging):\n\n```shell\n$ foliant make tex -p my-project\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking docx with Pandoc... Done\n─────────────────────\nResult: My_Project-2020-12-04.tex\n```\n\n\n## Config\n\nYou don't have to put anything in the config to use Pandoc backend. If it's installed, Foliant will detect it.\n\nYou can however customize the backend with options in `backend_config.pandoc` section:\n\n```yaml\nbackend_config:\n  pandoc:\n    pandoc_path: pandoc\n    build_whole_project: true\n    template: !path template.tex\n    vars:\n      ...\n    meta:\n      ...\n    reference_docx: !path reference.docx\n    reference_odt: !path reference.odt\n    css: !path epub.css\n    params:\n      ...\n    filters:\n      ...\n    markdown_flavor: markdown\n    markdown_extensions:\n      ...\n    slug: My_Awesome_Custom_Slug\n```\n\n`pandoc_path`\n:   is the path to `pandoc` executable. By default, it's assumed to be in the `PATH`.\n\n`build_whole_project`\n:   *added in 1.1.0* If `true`, whole project will be built into a single flat document. Default: `true`.\n\n`template`\n:   is the path to the TeX template to use when building pdf and tex (see [“Templates”](http://pandoc.org/MANUAL.html#templates) in the Pandoc documentation).\n\n    \u003e **Tip**\n    \u003e\n    \u003e Use `!path` tag to ensure the value is converted into a valid path relative to the project directory.\n\n`vars`\n:   is a mapping of template variables and their values. They will be added to pandoc command as `--variable key[=val]`.\n\n`meta`\n:   is a mapping of document metadata properties and their values. They will be added to pandoc command as `--metadata key[=val]`.\n\n`reference_docx`\n:   is the path to the reference document to be used when building docx (see **--reference-doc** option info in the Pandoc  [Options](https://pandoc.org/MANUAL#options-affecting-specific-writers) documentation).\n\n`reference_odt`\n:   is the path to the reference document to be used when building odt (see **--reference-doc** option info in the Pandoc  [Options](https://pandoc.org/MANUAL#options-affecting-specific-writers) documentation).\n\n`css`\n:   is the path to the stylesheets to be used when building epub (see **--css** option info in the Pandoc  [Options](https://pandoc.org/MANUAL#options-affecting-specific-writers) documentation).\n\n`params`\n:   are passed to the `pandoc` command. Params should be defined by their long names, with dashes replaced with underscores (e.g. `--pdf-engine` is defined as `pdf_engine`).\n\n`filters`\n:   is a list of Pandoc filters to be applied during build.\n\n`markdown_flavor`\n:   is the Markdown flavor assumed in the source. Default is `markdown`, [Pandoc's extended Markdown](http://pandoc.org/MANUAL.html#pandocs-markdown). See [“Markdown Variants”](http://pandoc.org/MANUAL.html#markdown-variants) in the Pandoc documentation.\n\n`markdown_extensions`\n:   is a list of Markdown extensions applied to the Markdown source. See [Pandoc’s Markdown](http://pandoc.org/MANUAL.html#pandocs-markdown) in the Pandoc documentation.\n\n`slug`\n:    is the result file name without suffix (e.g. `.pdf`). Overrides top-level config option `slug`.\n\nExample config:\n\n```yaml\nbackend_config:\n  pandoc:\n    template: !path templates/basic.tex\n    vars:\n      toc: true\n      title: This Is a Title\n      second_title: This Is a Subtitle\n      logo: !path templates/logo.png\n      year: 2020\n    params:\n      pdf_engine: xelatex\n      listings: true\n      number_sections: true\n    markdown_extensions:\n      - simple_tables\n      - fenced_code_blocks\n      - strikeout\n```\n\n## Build modes\n\nSince 1.1.0 you can build parts of your project into separate PDFs, along with the main PDF of the whole project.\n\nIf the `build_whole_project` parameter of Pandoc backend config is `true`, the whole project will be built in to a flat document as usual. You can disable it by switching `build_whole_project` to false.\n\nYou can also build parts of your project into separate documents. To configure such behavior we will be adding [Metadata](https://foliant-docs.github.io/docs/meta/) to chapters or even smaller sections.\n\nTo build a chapter into a separate document, add the following `meta` tag to your chapter's source:\n\n```\n\u003cmeta\n  pandoc=\"\n    vars:\n      toc: true\n      title: Our Awesome Product\n      second_title: Specifications\n      logo: templates/logo.png\n      year: 2020\n  \"\u003e\u003c/meta\u003e\n\n# Specifications\n\nsize: 15\nweight: 59\nlifespan: 9\n```\n\nIn the example above we have added a `meta` tag with `pandoc` field, in which we have overriden the `vars` mapping. The `pandoc` field is essential in this case. This is how backend determines that we want this chapter built separately. If you don't want to override any parameters, you can just add `pandoc=\"true\"` field.\n\n**All parameters which are not overriden in the meta tag will be taken from main config `foliant.yml`**.\n\nNow, as the `pandoc` field is present in one of the meta tags in the project, Pandoc backend should build not one but two documents. Let's check if it's true:\n\n```shell\n$ foliant make pdf\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking pdf with Pandoc... Done\n─────────────────────\nResult:\nMy_Project-2020-12-04.pdf\nSpecifications-2020-12-04.pdf\n```\n\nThat's right, we've got the main PDF with whole project and another pdf, with just the Specifications chapter.\n\nIf you wish to build even smaller piece of the project into separate file, add meta tag under the heading which you want to build:\n\n```\n# Specifications\n\nsize: 15\nweight: 59\nlifespan: 9\n\n## Additional info\n\n\u003cmeta\n  pandoc=\"\n    slug: additional\n    vars:\n      toc: true\n      title: Our Awesome Product\n      second_title: Additional info\n      logo: templates/logo.png\n      year: 2020\n  \"\u003e\u003c/meta\u003e\n\nLorem ipsum dolor sit amet consectetur adipisicing elit. Deleniti quos provident dolores eligendi nam quia sequi et tempore enim blanditiis, consequatur nostrum nulla dolor laborum quasi molestiae perspiciatis magni error consectetur nesciunt eaque veritatis voluptates! Cupiditate illum enim id recusandae assumenda excepturi odit tempore incidunt, amet soluta necessitatibus corrupti, aliquam.\n\n```\n\nIn this example only the Additional info section will be built into a separate document. Notice that we've also given it its own slug.\n\nLet's build again and look at the results:\n\n```shell\n$ foliant make pdf\nParsing config... Done\nApplying preprocessor flatten... Done\nMaking pdf with Pandoc... Done\n─────────────────────\nResult:\nMy_Project-2020-12-04.pdf\nadditional.pdf\n```\n\n## Troubleshooting\n\n### Could not convert image ...: check that rsvg2pdf is in path\n\nIn order to use svg images in pdf, you need to have `rsvg-convert` executable in `PATH`.\n\nOn macOS, `brew install librsvg` does the trick. On Ubuntu, `apt install librsvg2-bin`. On Windows, [download `rsvg-convert.7z`](http://opensourcepack.blogspot.ru/2012/06/rsvg-convert-svg-image-conversion-tool.html) (without fontconfig support), unpack `rsvg-convert.exe`, and put it anywhere in `PATH`. For example, you can put it in the same directory where you run `foliant make`.\n\n### LaTeX listings package does not work correctly with non-ASCII characters, e.g. Cyrillic letters\n\nIf you use non-ASCII characters inside backticks in your document, you can see an error like this:\n\n```bash\nError producing PDF.\n! Undefined control sequence.\n\\lst@arg -\u003egit clone [SSH-к\n                           люч]\nl.627 ...through{\\lstinline!git clone [SSH-ключ]!}\n```\n\nTo fix it, set `listings` parameter to `false`:\n\n```yaml\nbackend_config:\n  pandoc:\n    ...\n    params:\n      pdf_engine: xelatex\n      listings: false\n      number_sections: true\n    ...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.pandoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.pandoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.pandoc/lists"}