{"id":30873602,"url":"https://github.com/htdebeer/pandocomatic","last_synced_at":"2025-09-07T23:11:57.151Z","repository":{"id":15557359,"uuid":"18292500","full_name":"htdebeer/pandocomatic","owner":"htdebeer","description":"Automate the use of pandoc","archived":false,"fork":false,"pushed_at":"2025-04-19T07:18:32.000Z","size":5098,"stargazers_count":165,"open_issues_count":0,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-07-28T07:40:15.270Z","etag":null,"topics":["pandoc","paru","ruby","static-site-generator"],"latest_commit_sha":null,"homepage":"https://heerdebeer.org/Software/markdown/pandocomatic/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/htdebeer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2014-03-31T12:36:42.000Z","updated_at":"2025-04-19T07:18:35.000Z","dependencies_parsed_at":"2022-07-26T17:15:06.766Z","dependency_job_id":"3fa0e913-4a90-44bb-a339-6ef3be5dd238","html_url":"https://github.com/htdebeer/pandocomatic","commit_stats":{"total_commits":274,"total_committers":10,"mean_commits":27.4,"dds":"0.18613138686131392","last_synced_commit":"dd75205c5645d0a25009d792e3e521d40e494b6e"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/htdebeer/pandocomatic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htdebeer%2Fpandocomatic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htdebeer%2Fpandocomatic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htdebeer%2Fpandocomatic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htdebeer%2Fpandocomatic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/htdebeer","download_url":"https://codeload.github.com/htdebeer/pandocomatic/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/htdebeer%2Fpandocomatic/sbom","scorecard":{"id":471082,"data":{"date":"2025-08-11","repo":{"name":"github.com/htdebeer/pandocomatic","commit":"117253eabaf92d31c604b254220ec6cdeb338731"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.5,"checks":[{"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":"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":"Code-Review","score":0,"reason":"Found 0/30 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":"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":"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":"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":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"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":"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":"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":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: GNU General Public License v3.0: 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":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"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":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating ruby:3.4 to ruby:3.4@sha256:8b541f8279f3e960c74ff31fb8fd523c59d82725c9fb921d504e9078d553c862","Info:   0 out of   1 containerImage dependencies pinned"],"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":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact 2.1.0 not signed: https://api.github.com/repos/htdebeer/pandocomatic/releases/213338007","Warn: release artifact 2.0.0 not signed: https://api.github.com/repos/htdebeer/pandocomatic/releases/179046759","Warn: release artifact 1.1.3 not signed: https://api.github.com/repos/htdebeer/pandocomatic/releases/167578242","Warn: release artifact 1.1.1 not signed: https://api.github.com/repos/htdebeer/pandocomatic/releases/91865159","Warn: release artifact 1.0.0 not signed: https://api.github.com/repos/htdebeer/pandocomatic/releases/74843409","Warn: release artifact 2.1.0 does not have provenance: https://api.github.com/repos/htdebeer/pandocomatic/releases/213338007","Warn: release artifact 2.0.0 does not have provenance: https://api.github.com/repos/htdebeer/pandocomatic/releases/179046759","Warn: release artifact 1.1.3 does not have provenance: https://api.github.com/repos/htdebeer/pandocomatic/releases/167578242","Warn: release artifact 1.1.1 does not have provenance: https://api.github.com/repos/htdebeer/pandocomatic/releases/91865159","Warn: release artifact 1.0.0 does not have provenance: https://api.github.com/repos/htdebeer/pandocomatic/releases/74843409"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"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"}}]},"last_synced_at":"2025-08-19T13:54:15.713Z","repository_id":15557359,"created_at":"2025-08-19T13:54:15.714Z","updated_at":"2025-08-19T13:54:15.714Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274107977,"owners_count":25223473,"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","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["pandoc","paru","ruby","static-site-generator"],"created_at":"2025-09-07T23:11:49.819Z","updated_at":"2025-09-07T23:11:57.135Z","avatar_url":"https://github.com/htdebeer.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Gem\nVersion](https://badge.fury.io/rb/pandocomatic.svg)](https://badge.fury.io/rb/pandocomatic)\n\n# Pandocomatic—Automate the use of pandoc\n\nPandocomatic automates the use of [pandoc](https://pandoc.org/). With\npandocomatic you can express common patterns of using pandoc for\ngenerating your documents. Applied to a directory, pandocomatic acts as\na static site generator. For example, this manual is generated with\npandocomatic!\n\nPandocomatic is [free\nsoftware](https://www.gnu.org/philosophy/free-sw.en.html); pandocomatic\nis released under the\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html). You will find the\nsource code of pandocomatic in its\n[repository](https://github.com/htdebeer/pandocomatic) on\n[Github](https://github.com).\n\n**Note.** Pandocomatic is build on top of\n[paru](https://github.com/htdebeer/paru), which is a wrapper around\npandoc.\n\n**Note.** As I am a GNU/Linux user, I do not officially support other\noperating systems like Mac OSX or Windows. Fixes and patches for those\noperating systems are welcome.\n\nSee [pandocomatic’s\nmanual](https://heerdebeer.org/Software/markdown/pandocomatic/) for an\nextensive description of pandocomatic.\n\n## Why pandocomatic?\n\nI use pandoc a lot. I use it to write all my papers, notes, websites,\nreports, outlines, summaries, and books. Time and again I was invoking\npandoc like:\n\n``` bash\npandoc --from markdown \\\n  --to html \\\n  --standalone \\\n  --csl apa.csl \\\n  --bibliography my-bib.bib \\\n  --mathjax \\\n  --output result.html \\\n  source.md\n```\n\nSure, when I write about history, the [CSL](https://citationstyles.org/)\nfile and bibliography change. And I do not need the `--mathjax` option\nlike I do when I am writing about mathematics education. Still, all\nthese invocations are quite similar.\n\nI already wrote the program *do-pandoc.rb* as part of a Ruby wrapper\naround pandoc, [paru](https://heerdebeer.org/Software/markdown/paru/).\nUsing *do-pandoc.rb* I can specify the options to pandoc in a metadata\nblock in the source file itself. With *do-pandoc.rb* the invocation\nabove is simplified to:\n\n``` bash\ndo-pandoc.rb source.md\n```\n\nIt saves me from typing out the whole pandoc invocation each time I run\npandoc on a source file. However, I have still to setup the same options\nto use in each document that I am writing, even though these options do\nnot differ that much from document to document.\n\n*Pandocomatic* is a tool to re-use these common configurations by\nspecifying a so-called *pandocomatic template* in a\n[YAML](https://yaml.org/) configuration file. For example, by placing\nthe following file, `pandocomatic.yaml`, in pandoc’s data directory:\n\n``` yaml\ntemplates:\n  education-research:\n    preprocessors: []\n    pandoc:\n      from: markdown\n      to: html\n      standalone: true\n      csl: 'apa.csl'\n      toc: true\n      bibliography: /path/to/bibliography.bib\n      mathjax: true\n    postprocessors: []\n```\n\nIn this configuration file a single *pandocomatic template* is being\ndefined: *education-research*. This template specifies that the source\nfiles it is applied to are not being preprocessed. Furthermore, the\nsource files are converted with pandoc by invoking\n`pandoc --from markdown --to html --standalone --csl apa.csl --toc --bibliography /path/to/bibliography.bib --mathjax`.\nFinally, the template specifies that pandoc’s output is not being\npostprocessed.\n\nI now can create a new document that uses this template by including the\nfollowing metadata block in my source file, `on_teaching_maths.md`:\n\n``` pandoc\n ---\n title: On teaching mathematics\n author: Huub de Beer\n pandocomatic_:\n   use-template: education-research\n   pandoc:\n     output: on_teaching_mathematics.html\n ...\n \n Here goes the contents of my new paper ...\n```\n\nTo convert this file to `on_teaching_mathematics.html` I run\npandocomatic:\n\n``` bash\npandocomatic -i on_teaching_maths.md\n```\n\nWith just two extra lines in a metadata block I can tell pandocomatic\nwhat template to use when converting a file. You can also use multiple\ntemplates in a document, for example to convert a markdown file to both\nHTML and PDF. Adding file-specific pandoc options to the conversion\nprocess is as easy as adding a `pandoc` property with those options to\nthe `pandocomatic_` metadata property in the source file like I did with\nthe `output` property in the example above.\n\nOnce I had written a number of related documents this way, it was a\nsmall step to enable pandocomatic to convert directories as well. Just\nlike that, pandocomatic can be used as a *static site generator*!\n\nPandocomatic is [free\nsoftware](https://www.gnu.org/philosophy/free-sw.en.html); pandocomatic\nis released under the\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html). You find\npandocomatic’s source code on\n[github](https://github.com/htdebeer/pandocomatic).\n\n## Installation\n\nPandocomatic is a [Ruby](https://www.ruby-lang.org/en/) program and can\nbe installed through [RubyGems](https://rubygems.org/) as follows:\n\n``` bash\ngem install pandocomatic\n```\n\nThis will install pandocomatic and\n[paru](https://heerdebeer.org/Software/markdown/paru/), a Ruby wrapper\naround pandoc. To use pandocomatic, you also need a working pandoc\ninstallation. See [pandoc’s installation\nguide](https://pandoc.org/installing.html) for more information about\ninstalling pandoc.\n\n### Docker\n\nYou can also build and install the latest version yourself by running\nthe following commands:\n\n``` bash\ncd /directory/you/downloaded/the/gem/to\ndocker image build --tag pandocomatic:dev .\ndocker container run --rm -it --volume $(pwd):/home/pandocomatic-user pandocomatic:dev bundle exec rake build\ngem install pkg/pandocomatic-2.1.0.gem\n```\n\nYou only have to do the second step one time. Once you’ve created a\ndocker image, you can reuse it as is until `Dockerfile` changes.\n\n### MacOS: Brew\n\nAlternatively, MacOS users can install pandocomatic via\n[homebrew](https://formulae.brew.sh/formula/pandocomatic):\n\n``` bash\nbrew install pandocomatic\n```\n\n## Examples\n\n### Convert a single file\n\nConvert `hello.md` to `hello.html` according to the configuration in\n`pandocomatic.yaml`:\n\n``` bash\npandocomatic --config pandocomatic.yaml -o hello.html -i hello.md\n```\n\n### Convert a directory\n\nGenerate a static site using data directory `assets`, but only convert\nfiles that have been updated since the last time pandocomatic has been\nrun:\n\n``` bash\npandocomatic --data-dir assets/ -o website/ -i source/ -m\n```\n\n### Generating pandocomatic’s manual and README files\n\nGenerate the markdown files for pandocomatic’s\n[manual](https://heerdebeer.org/Software/markdown/pandocomatic/) and its\n[github repository](https://github.com/htdebeer/pandocomatic) README:\n\n``` bash\ngit clone https://github.com/htdebeer/pandocomatic.git\ncd documentation\npandocomatic -d data-dir -c config.yaml -i README.md -o ../README.md\npandocomatic -d data-dir -c config.yaml -i manual.md -o ../index.md\n```\n\nBe careful to not overwrite the input file with the output file! I would\nsuggest using different names for both, or different directories.\nLooking more closely to the pandocomatic configuration file\n`config.yaml`, we see it contains one template, `mddoc`:\n\n``` yaml\n templates:\n   mddoc:\n     pandoc:\n       from: markdown\n       to: markdown\n       standalone: true\n       filter: \n       - filters/insert_document.rb\n       - filters/insert_code_block.rb\n       - filters/remove_pandocomatic_metadata.rb\n       - filters/insert_pandocomatic_version.rb\n   indexdoc:\n       extends: mddoc\n       postprocessors: ['postprocessors/setup_for_website.rb']\n```\n\nThe `mddoc` template tells pandocomatic to convert a markdown file to a\nstandalone markdown file using three filters: `insert_document.rb`,\n`insert_code_block.rb`, and `remove_pandocomatic_metadata.rb`. The first\ntwo filters allow you to include another markdown file or to include a\nsource code file (see the README listing below). The last filter removes\nthe pandocomatic metadata block from the file so the settings in it do\nnot interfere when, later on, `manual.md` is converted to HTML. These\nfilters are located in the\n[`filters`](https://github.com/htdebeer/pandocomatic/tree/master/documentation/data-dir/filters)\nsubdirectory in the specified data directory `data-dir`.\n\nHowever, the `mddoc` template converts from and to pandoc’s markdown\nvariant, which differs slightly from the markdown variant used by\n[Github](https://github.com/) for README files. Luckily, pandoc does\nsupport writing Github’s markdown variant. There is no need to create\nand use a different template for generating the README, though, as you\ncan override all template’s settings inside a pandocomatic block in a\nmarkdown file:\n\n``` markdown\n ---\n pandocomatic_:\n   use-template: mddoc\n   pandoc:\n     to: markdown_github\n ...\n \n # Pandocomatic—Automate the use of pandoc\n \n ::paru::insert introduction.md\n \n ## Why pandocomatic?\n \n ::paru::insert why_pandocomatic.md\n \n ## Licence\n \n ::paru::insert license.md\n \n ## Installation\n \n ::paru::insert install.md\n \n ## Examples\n \n ::paru::insert usage_examples.md\n \n ## More information\n \n See [pandocomatic's\n manual](https://heerdebeer.org/Software/markdown/pandocomatic/) for more\n extensive examples of using pandocomatic. Notably, the manual contains two\n typical use cases of pandocomatic:\n \n 1.  [automating setting up and running pandoc for a series of related papers](https://heerdebeer.org/Software/markdown/pandocomatic/#automating-setting-up-and-running-pandoc-for-a-series-of-related-papers), and \n 2.  [using pandocomatic as a static site\n      generator](https://heerdebeer.org/Software/markdown/pandocomatic/#using-pandocomatic-as-a-static-site-generator).\n```\n\nHere you see that the README uses the `mddoc` template and it overwrites\nthe `to` property with `markdown_github`.\n\nSimilarly, in the input file\n[`manual.md`](https://github.com/htdebeer/pandocomatic/blob/master/documentation/manual.md),\nan extra filter is specified,\n[‘number_chapters_and_sections_and_figures.rb’](https://github.com/htdebeer/pandocomatic/blob/master/documentation/data-dir/filters/number_chapters_and_sections_and_figures.rb),\nto number the chapters and sections in the manual, which is not needed\nfor the README, by using the following pandocomatic metadata in the\nmanual input file:\n\n``` yaml\npandocomatic_:\n  use-template: mddoc\n  pandoc:\n    filter: \n    - 'filters/number_chapters_and_sections_and_figures.rb'\n```\n\nPandocomatic allows you to generalize common aspects of running pandoc\nwhile still offering the ability to be as specific as needed.\n\n## More information\n\nSee [pandocomatic’s\nmanual](https://heerdebeer.org/Software/markdown/pandocomatic/) for more\nextensive examples of using pandocomatic.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtdebeer%2Fpandocomatic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhtdebeer%2Fpandocomatic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhtdebeer%2Fpandocomatic/lists"}