{"id":41787422,"url":"https://github.com/rnwst/pandoc-lua-types","last_synced_at":"2026-01-25T04:31:45.493Z","repository":{"id":279985102,"uuid":"940657820","full_name":"rnwst/pandoc-lua-types","owner":"rnwst","description":"Type checking for pandoc Lua filters.","archived":false,"fork":false,"pushed_at":"2025-10-10T16:26:32.000Z","size":246,"stargazers_count":4,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-25T16:46:05.867Z","etag":null,"topics":["language-server","lua","pandoc","pandoc-filter"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rnwst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2025-02-28T15:06:27.000Z","updated_at":"2025-10-10T16:26:35.000Z","dependencies_parsed_at":"2025-02-28T20:41:37.134Z","dependency_job_id":"c93dcd85-e62a-4aba-b3ce-7e8d773c4247","html_url":"https://github.com/rnwst/pandoc-lua-types","commit_stats":null,"previous_names":["rnwst/pandoc-lua-types"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rnwst/pandoc-lua-types","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwst%2Fpandoc-lua-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwst%2Fpandoc-lua-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwst%2Fpandoc-lua-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwst%2Fpandoc-lua-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rnwst","download_url":"https://codeload.github.com/rnwst/pandoc-lua-types/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnwst%2Fpandoc-lua-types/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28743492,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T02:46:29.005Z","status":"ssl_error","status_checked_at":"2026-01-25T02:44:29.968Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["language-server","lua","pandoc","pandoc-filter"],"created_at":"2026-01-25T04:31:45.378Z","updated_at":"2026-01-25T04:31:45.487Z","avatar_url":"https://github.com/rnwst.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pandoc-lua-types\n\nMake writing [Pandoc](https://pandoc.org/) [Lua filters](https://pandoc.org/lua-filters.html) a pleasure by using these language server definitions for use with [`lua-language-server`](https://github.com/LuaLS/lua-language-server).\nThe definitions include Pandoc's element types as well as function definitions for the [`pandoc`](https://pandoc.org/lua-filters.html#module-pandoc) module, enabling **static type checking, autocompletion, and automatic display of documentation**.\n\n## Installation\n\nThe `pandoc-types.lua` definition file can be added to your pandoc filter git repository by adding this project as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules):\n```console\ngit submodule add https://github.com/rnwst/pandoc-lua-types types\n```\nTo enable LuaLS to find the definition file in `./types/`, a `.luarc.json` file needs to be created in the root of the project with the following contents:\n```json\n{\n  \"workspace\": {\n    \"library\": [\"types\"]\n  }\n}\n```\n\n## Type annotations and static type checking\n\nLuaLS' type checking is [not currently as capable as it could be](https://github.com/LuaLS/lua-language-server/issues/3101), however it still seems to catch at least 90% of my errors that could be caught by static type checking, making it well worth the effort!\n\nA basic understanding of LuaLS' [type annotation syntax](https://luals.github.io/wiki/annotations/) is presumed in this section.\n\nAll of Pandoc's [Block](https://pandoc.org/lua-filters.html#type-block) and [Inline](https://pandoc.org/lua-filters.html#type-inline) elements are available for type annotations. Furthermore, the [`Pandoc`](https://pandoc.org/lua-filters.html#type-pandoc) and [`Meta`](https://pandoc.org/lua-filters.html#type-meta) types are available as well, and so are the various [Element component](https://pandoc.org/lua-filters.html#element-components) types. This enables static type checking when writing filter functions. For example:\n```Lua\n---Filter function for Spans\n---@param span Span\n---@return Span | nil\nfunction Span(span)\n   -- This triggers a type error from LuaLS since the `content` field\n   -- is a sequence of Inlines and does not match a string!\n   span.content = 'foobar'\nend\n```\nApart from individual Block and Inline element types, the types `Block` and `Inline` have also been defined, which act as an alias for any Block or Inline element, respectively.\n\nFor sequences of Blocks and Inlines, the `Blocks` and `Inlines` types are available. They differ from `Block[]` and `Inline[]` by having the [`walk`](https://pandoc.org/lua-filters.html#type-blocks:walk) and [`clone`](https://pandoc.org/lua-filters.html#clone) methods available on them, as well as all the [`List`](https://pandoc.org/lua-filters.html#module-pandoc.list)-methods (such as metamethods [`__concat`](https://pandoc.org/lua-filters.html#pandoc.list:__concat) and [`__eq`](https://pandoc.org/lua-filters.html#pandoc.list:__eq), and methods [`extend`](https://pandoc.org/lua-filters.html#pandoc.list:extend), [`filter`](https://pandoc.org/lua-filters.html#pandoc.list:filter), [`includes`](https://pandoc.org/lua-filters.html#pandoc.list:includes), ...). When a filter function is receiving Inlines, they are of type `Inlines`, but if you are returning a table of Inline elements as in the following example, they are of type `Inline[]`:\n```Lua\n---Filter function for Inlines\n---@param inlines Inlines\n---@param return Inline[]\nfunction Inlines(inlines)\n   return {pandoc.Str('Hello!')}\nend\n```\nIf you are unsure if your return value is of type `Inline[]` or `Inlines`, you can annotate it as `Inlines | Inline[]`, which covers both types.\n\nThere is currently a bug in LuaLS preventing it from doing proper type-checking on the contents of a variable of type `Inlines` or `Blocks`. As a workaround, such variables can be assigned the type `(Inlines | Inline[])` (and equivalently for `Blocks`), as in the following example. When assigning a `Block` or `Inline` type to a more specific type (such as a Span, as in the following example), the [`@cast` annotation](https://luals.github.io/wiki/annotations/#cast) can be used to cast the variable to the required type:\n```Lua\n---Inlines filter function\n---@param inlines (Inlines | Inline[])\nfunction Inlines(inlines)\n   if inlines[1].tag == 'Span' then\n      local span = inlines[1]\n      ---@cast span Span\n      ...\n   end\n   ...\nend\n```\n\nType definitions are also available for filters and filter functions. The `Filter` type can be used to annotate a Lua filter's return value:\n```Lua\n---@type Filter\nreturn {\n   traverse = 'topdown',\n   Str = filter_fn1,\n   Para = filter_fn2,\n}\n```\nThe `Filter` type is either a `FilterTable`, or an array of `FilterTable`s, or an array of an array of `FilterTable`s, and so on. A `FilterTable` is a table of filter functions (the return value above is an example). Therefore, in the above example, the `---@type FilterTable` annotation could have been used as well (though if a nested table was returned, the `Filter` type would have to be used).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnwst%2Fpandoc-lua-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frnwst%2Fpandoc-lua-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnwst%2Fpandoc-lua-types/lists"}