{"id":16880325,"url":"https://github.com/tarleb/lua-filter-template","last_synced_at":"2025-03-22T07:32:11.490Z","repository":{"id":37802113,"uuid":"450029531","full_name":"tarleb/lua-filter-template","owner":"tarleb","description":"All the tools to publish a pandoc Lua filter quickly and easily; work in progress.","archived":false,"fork":false,"pushed_at":"2024-11-25T13:58:51.000Z","size":44,"stargazers_count":16,"open_issues_count":3,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-18T09:37:40.893Z","etag":null,"topics":["lua","pandoc-filter","quarto-extension","quarto-filter"],"latest_commit_sha":null,"homepage":"","language":"Makefile","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/tarleb.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}},"created_at":"2022-01-20T09:19:11.000Z","updated_at":"2025-01-25T20:50:50.000Z","dependencies_parsed_at":"2024-07-07T19:28:44.147Z","dependency_job_id":"2f3f1d6f-bb28-4a86-866f-1ef03f036078","html_url":"https://github.com/tarleb/lua-filter-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarleb%2Flua-filter-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarleb%2Flua-filter-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarleb%2Flua-filter-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarleb%2Flua-filter-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarleb","download_url":"https://codeload.github.com/tarleb/lua-filter-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244925175,"owners_count":20532873,"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":["lua","pandoc-filter","quarto-extension","quarto-filter"],"created_at":"2024-10-13T15:58:21.055Z","updated_at":"2025-03-22T07:32:11.485Z","avatar_url":"https://github.com/tarleb.png","language":"Makefile","readme":"Greetings, a Lua Filter Template\n==================================================================\n\n[![GitHub build status][CI badge]][CI workflow]\n\nGreetings is a friendly Lua filter that adds a welcoming message\nto the document.\n\n[CI badge]: https://img.shields.io/github/actions/workflow/status/tarleb/lua-filter-template/ci.yaml?branch=main\n[CI workflow]: https://github.com/tarleb/lua-filter-template/actions/workflows/ci.yaml\n\n* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\n\nThis repository serves as a template intended to make publishing\nof pandoc [Lua filters][] easy and convenient. Just click \"use\nthis template\" and then make modifications in your new repository.\nSee also the GitHub documentation on [creating a repository from a\ntemplate][from template].\n\n[Lua filters]: https://pandoc.org/lua-filters.html\n[from template]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template\n\nTemplate Usage\n------------------------------------------------------------------\n\nThis section describes how to use the template.\n\n### Checklist\n\nA few things should be updated in the repository after cloning\nthis template. You can use the checklist below to ensure that you\nget the most out of it. We recommend that you perform at least the\nfirst two steps, everything else is up to you.\n\n0. [ ] **Use template**: Create a new repo from\n   this template. Use the name that you want to give your filter\n   as a repository name. E.g., a repository for filter\n   `greetings.lua` should be named `greetings`.\n1. [ ] **Clone your new repository**: Run `git clone` to fetch\n   your new repository.\n2. [ ] **Setup the filter**: the easiest way to setup the\n   repository is to run\n\n   ``` bash\n   make setup\n   ```\n\n   This will update the README, remove the template-specific\n   documentation, and rename the filter; the repository name is\n   used to determine the new filter name.\n\n3. [ ] **Update the README**: Describe your filter, so people\n   will know what to expect. You may also want to update the URLs\n   in the links above to match your repository.\n\n4. [ ] (optional) **Choose default test output formats**. Replace\n   the `FORMAT=native` line in Makefile with your desired default\n   output formats for tests, e.g. `FORMAT=html latex`. These must\n   be possible values of Pandoc's `--to` option.\n\n4. [ ] (optional) **Setup Quarto extension**: This step is\n   recommended if you want to make it easy for [Quarto][] users to\n   install and use your filter: Quarto expects the filter to be\n   placed in the `_extensions` folder, packed together with a YAML\n   file containing relevant metadata. Run\n\n   ``` bash\n   make quarto-extension\n   ```\n\n   to generate the necessary files and directories. You should\n   commit the generated files to source control. See also the\n   [`quarto-extension` documentation](quarto-extension) below.\n\n5. [ ] (optional) **Tag a release**: The easiest way to create a\n   new release is to run `make release VERSION=0.0.1`. This will\n   update the Quarto extension, commit the changes, then tag the\n   resulting commit with the given VERSION. This step is\n   recommended if the filter is distributed as a Quarto extension.\n\n### Development\n\nThe repository comes with a `Makefile` intended to make developing\na filter a pleasant experience. You may want to adjust some of the\ntargets while keeping the general structure.\n\nUse the Makefile with `make ...`, where `...` denotes one of the\ntargets listed in this section.\n\n#### `generate`\n\n(Re)generate test output files. This target runs your filter on the\nfile `test/input.md` and generates one or more output files\n`test/expected.\u003cFORMAT\u003e` (`native` by default).\n\nChange desired output formats by replacing the Makefile's `FORMAT=...`\nline with e.g. `FORMAT=html docx`. These must be possible values of\nPandoc's `--to` option.\n\nYou can also set `FORMAT` on the command line to regenerate files in\nspecific output formats:\n\n```bash\nmake regenerate FORMAT=docx\n```\n\nFiles are generated using the Pandoc default options given in\n`test/test.yaml`. This file is provided by default but you may want\nto check it into source control and modify it as needed.\n\n#### `test`\n\nTests the filter. This target runs your filter on the file\n`test/input.md` using Pandoc options `test/test.yaml` and compares\nthe result with one or more `test/expected.\u003cFORMAT\u003e` files\n(`native` by default).\n\nSee the `regenerate` target on how to change default `FORMAT` values\nor passing it on the command lines.\n\n#### `quarto-extension`\n\nThis target sets the repository up to be used as a [Quarto][]\nextension. The target will create the directory structure expected\nby quarto. It will also generate a `_extension.yml` metadata file.\nInvoking this target will move the main `.lua` file below the\n`_extensions` directory; the the original file will be replaced\nwith a symlink.\n\n[Quarto]: https://quarto.org\n\n#### `release`\n\nCreates a new release for the given version. The version must be\npassed as a variable:\n\n``` bash\nmake release VERSION=1.0.0\n```\n\nThe `release` target depends on `quarto-extension`.\n\n#### `update-name`\n\nRun this target after renaming the filter file. It will update the\nname in all other files.\n\n#### `website`\n\nGenerates a website for this filter. The website will contain the\ncontents of this README, an example generated from the test input,\nas well as the full filter code. The page components are combined\nwith the `.tools/docs.lua` filter.\n\n### Website\n\nThe repository template comes with a GitHub Action to publish a\nwebsite via GitHub pages. It expects the new \"GitHub Actions\"\nsource to be used for Pages.\n\nRemove the file `.github/workflows/website.yml` to disable this\nfeature.\n\n* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *\n\nUsage\n------------------------------------------------------------------\n\nThe filter modifies the internal document representation; it can\nbe used with many publishing systems that are based on pandoc.\n\n### Plain pandoc\n\nPass the filter to pandoc via the `--lua-filter` (or `-L`) command\nline option.\n\n    pandoc --lua-filter greetings.lua ...\n\n### Quarto\n\nUsers of Quarto can install this filter as an extension with\n\n    quarto install extension tarleb/greetings\n\nand use it by adding `greetings` to the `filters` entry\nin their YAML header.\n\n``` yaml\n---\nfilters:\n  - greetings\n---\n```\n\n### R Markdown\n\nUse `pandoc_args` to invoke the filter. See the [R Markdown\nCookbook](https://bookdown.org/yihui/rmarkdown-cookbook/lua-filters.html)\nfor details.\n\n``` yaml\n---\noutput:\n  word_document:\n    pandoc_args: ['--lua-filter=greetings.lua']\n---\n```\n\nLicense\n------------------------------------------------------------------\n\nThis pandoc Lua filter is published under the MIT license, see\nfile `LICENSE` for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarleb%2Flua-filter-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarleb%2Flua-filter-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarleb%2Flua-filter-template/lists"}