{"id":23151002,"url":"https://github.com/coatless-quarto/catchandrelease","last_synced_at":"2025-05-08T02:35:19.172Z","repository":{"id":205437012,"uuid":"714200879","full_name":"coatless-quarto/catchandrelease","owner":"coatless-quarto","description":"R\u0026D Quarto extension to capture output and replace it elsewhere in document","archived":false,"fork":false,"pushed_at":"2023-11-04T20:48:19.000Z","size":425,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-12-17T18:19:49.891Z","etag":null,"topics":["experiment","lua","lua-filter","pandoc","pandoc-filter","quarto","quarto-extension"],"latest_commit_sha":null,"homepage":"http://quarto.thecoatlessprofessor.com/catchandrelease/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coatless-quarto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-11-04T07:47:33.000Z","updated_at":"2023-11-05T11:27:37.000Z","dependencies_parsed_at":"2023-11-04T20:20:51.192Z","dependency_job_id":null,"html_url":"https://github.com/coatless-quarto/catchandrelease","commit_stats":null,"previous_names":["coatless-quarto/collect","coatless-quarto/catchandrelease"],"tags_count":0,"template":false,"template_full_name":"coatless-devcontainer/quarto-extension-dev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coatless-quarto%2Fcatchandrelease","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coatless-quarto%2Fcatchandrelease/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coatless-quarto%2Fcatchandrelease/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coatless-quarto%2Fcatchandrelease/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coatless-quarto","download_url":"https://codeload.github.com/coatless-quarto/catchandrelease/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238039743,"owners_count":19406395,"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":["experiment","lua","lua-filter","pandoc","pandoc-filter","quarto","quarto-extension"],"created_at":"2024-12-17T18:19:46.404Z","updated_at":"2025-02-10T00:39:09.191Z","avatar_url":"https://github.com/coatless-quarto.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# catchandrelease: A Quarto Experiment on Reorganizing\n\nThe `catchandrelease` extension is a unique experiment designed to explore the identification, storage, and relocation of text within your Quarto documents.\n\n[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/coatless-quarto/catchandrelease)\n\n## Usage\n\nThe `catchandrelease` extension does not introduce significant enhancements to your document's content. Instead, it serves as an instructive example of how to identify, retrieve, and reposition content within your Quarto project.\n\n## Installation\n\nTo install the `catchandrelease` extension, follow these steps:\n\n1. Open your terminal.\n\n2. Execute the following command:\n\n```bash\nquarto add coatless-quarto/catchandrelease\n```\n\nThis command will download and install the extension under the `_extensions` subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.\n\n## Capturing Code\n\nIn Pandoc, various [Lua Types](https://pandoc.org/lua-filters.html#lua-type-reference) each have their own element filter functions that can be applied throughout a document. For example, when creating a code cell using Markdown like this:\n\n````markdown\n```{webr-r}\n# R code here\n```\n````\n\nInternally, Pandoc treats this as a [CodeBlock](https://pandoc.org/lua-filters.html#type-codeblock). To \"capture\" code, you can provide a custom filter function for this specific Lua type. For instance, you can traverse and process each `CodeBlock` element using the following Lua code:\n\n```lua\nfunction CodeBlock(elem)\n    -- Display the text of the CodeBlock\n    quarto.log.output(elem.text)\n\n    -- Return the CodeBlock unchanged\n    return elem\n}\n```\n\nWith some modifications, you can extract the text from each code block and store it within a global table:\n\n```lua\n-- Define a table to store the extracted code and attributes\nlocal codeBlocksTable = {}\n\nfunction captureCode(elem)\n  -- Extract code text and store it in a table\n  local codeBlockData = {\n    codeValue = elem.code\n  }\n  \n  -- Append the table to the codeBlocksTable\n  table.insert(codeBlocksTable, codeBlockData)\n  \n  -- Return the CodeBlock unchanged\n  return elem\n}\n\n-- Override Element filter function for CodeBlock\nreturn {\n  { CodeBlock = captureCode }\n}\n```\n\n## Releasing\n\nThe second part of the process involves releasing the captured content back into the document. There are various options for releasing the data, such as marking it up using other `Inline` or `Block` styles. Alternatively, you can merge and release the data, which is the approach taken here. This requires two functions: data combination and insertion.\n\nFor data combination, it is simpler to use JSON encoding of the Lua table storing the CodeBlock details, e.g., [`quarto.json.encode()`](https://quarto.org/docs/extensions/lua-api.html#json-encoding).\n\nFor the insertion part, you can provide a custom [`Pandoc`](https://pandoc.org/lua-filters.html#type-pandoc) function like this:\n\n```lua\n-- Call the function to combine CodeBlocks and write the output to the end of the document\nlocal function releaseCode(doc)\n\n  -- Convert the Lua table to JSON\n  local jsonCode = writeCodeBlocksToJson()\n\n  -- Create a new paragraph with the combined code \n  local para = pandoc.Para(jsonCode)\n\n  -- Add it to the end of the document\n  table.insert(doc.blocks, para)\n\n  -- Return the modified document\n  return doc\n}\n\n-- Override Element filter functions\nreturn {\n  { CodeBlock = captureCode },\n  { Pandoc = releaseCode}\n}\n```\n\nFor more details, refer to the `_extensions/` directory in the Quarto project's repository.\n\n## Note\n\nThe order in which the filter functions are applied follows the [Typewise traversal](https://pandoc.org/lua-filters.html#typewise-traversal) default sequence:\n\n1. Functions for Inline elements\n2. The Inlines filter function\n3. Functions for Block elements\n4. The Blocks filter function\n5. The Meta filter function\n6. The Pandoc filter function (last)\n\nTo enable further customization of the catching and releasing mechanism, you can define a custom Meta function, e.g., `customMeta()`, and specify the order as follows:\n\n```lua\nreturn {\n  { Meta = customMeta},            -- (1)\n  { CodeBlock = captureCode },     -- (2)\n  { Pandoc = releaseCode }         -- (3)\n}\n```\n\n# Conclusion\n\nBy using these techniques, you can efficiently re-organize content inside of Quarto.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoatless-quarto%2Fcatchandrelease","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoatless-quarto%2Fcatchandrelease","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoatless-quarto%2Fcatchandrelease/lists"}