{"id":16369699,"url":"https://github.com/dcsunset/pandoc-include","last_synced_at":"2025-04-07T06:12:45.833Z","repository":{"id":48287240,"uuid":"170474635","full_name":"DCsunset/pandoc-include","owner":"DCsunset","description":"A pandoc filter to allow file and header inclusion","archived":false,"fork":false,"pushed_at":"2024-08-17T18:07:22.000Z","size":389,"stargazers_count":65,"open_issues_count":10,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-12T02:55:59.161Z","etag":null,"topics":["markdown","pandoc","pandoc-filter","python"],"latest_commit_sha":null,"homepage":"","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/DCsunset.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-13T08:58:48.000Z","updated_at":"2024-10-08T23:53:20.000Z","dependencies_parsed_at":"2023-11-17T23:04:46.045Z","dependency_job_id":"3edf6cd6-a3c8-42fc-bc8c-f435d775be8e","html_url":"https://github.com/DCsunset/pandoc-include","commit_stats":{"total_commits":147,"total_committers":7,"mean_commits":21.0,"dds":"0.47619047619047616","last_synced_commit":"45b65df64d4b857792f9a8701d707b6cdd33d4d2"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCsunset%2Fpandoc-include","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCsunset%2Fpandoc-include/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCsunset%2Fpandoc-include/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DCsunset%2Fpandoc-include/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DCsunset","download_url":"https://codeload.github.com/DCsunset/pandoc-include/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601449,"owners_count":20964864,"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":["markdown","pandoc","pandoc-filter","python"],"created_at":"2024-10-11T02:56:04.569Z","updated_at":"2025-04-07T06:12:45.816Z","avatar_url":"https://github.com/DCsunset.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pandoc-include\n\n[![PyPI](https://img.shields.io/pypi/v/pandoc-include)](https://pypi.org/project/pandoc-include/)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/pandoc-include)](https://pypi.org/project/pandoc-include/)\n[![GitHub](https://img.shields.io/github/license/DCsunset/pandoc-include?color=blue)](https://github.com/DCsunset/pandoc-include)\n\nPandoc filter to allow including files and headers in a document.\n\n## Features\n\n* Include as raw blocks\n* Indent and dedent included contents\n* Partial include: Allow including only parts of the file using options\n* Code include: Allow using `!include` in code blocks\n* Unix style pathname\n* Recursive include: It depends on `include-entry` header to work\n* Yaml header Merging:\nWhen an included file has its header, it will be merged into the current header.\nIf there's a conflict, the original header of the current file remains.\n* Header include: Use `!include-header file.yaml` to include Yaml header from file.\n\n## TODO\n\n- [ ] Write options to a tmp file and pass the filename by environment variable\n\n## Installation\n\n### Using pip\n\nTo install the latest published version:\n\n```\npip install --user pandoc-include\n```\n\n\nTo install the current (development) version hosted on the repository, use\n\n```\npip install --upgrade --force --no-cache git+https://github.com/DCsunset/pandoc-include\n```\n\nTo check the version currently installed:\n\n```\npip show pandoc-include\n```\n\n### Using pipx\n\nIf `pip install` give you a `error: externally-managed-environment` error message, you may bypass this restriction using [pipx](https://github.com/pypa/pipx).\n\nTo install the latest published version:\n\n```\npipx install pandoc-include\n```\n\nTo install the current (development) version hosted on the repository, use\n\n```\npipx install --force git+https://github.com/DCsunset/pandoc-include\n```\n\nTo check the version currently installed, inspect the output of \n\n```\npipx list\n```\n\n\n### Using Nix\n\n`pandoc-include` is included in the Nixpkgs.\nSimply add the package to your NixOS config or use the following command:\n\n```sh\n# install in your profile\nnix-env -iA nixpkgs.pandoc-include\n\n# Or use it temporarily in a shell\nnix-shell -p pandoc-include\n```\n\n\n## Usage\n\n**Note**: you should use `pandoc` with version greater than or equal to `2.17`,\nwhich is the minimum version that is tested.\n\n### Command\n\nTo use this filter, add to pandoc command\n\n```\npandoc input.md --filter pandoc-include -o output.pdf\n```\n\n### Syntax\n\nEach include statement has its own line and has the syntax:\n\n```\n!include somefolder/somefile\n\n!include-header file.yaml\n```\n\nOr\n\n```\n$include somefolder/somefile\n\n$include-header file.yaml\n```\n\nEach include statement must be in its own paragraph. That is, in its own line\nand separated by blank lines.\n\n\nFor code include, use `!include` statement in a code block:\n\n````markdown\n```cpp\n!include filename.cpp\n```\n````\n\nThe path can be either absolute or relative to the **current** file's directory.\nBesides, [unix-style](https://en.wikipedia.org/wiki/Glob_(programming)) pathname can used.\n(If the include statement is used in an included file,\nthen the path is absolute or relative to the included file itself.)\n\nIf there are special characters in the filename, use quotes:\n\n```\n!include \"filename with space\"\n!include 'filename\"with\"quotes'\n```\n\nIf the filename contains special sequences in markdown, use backquotes:\n(**Note**: this also applies to include statment in code blocks)\n\n```\n!include `__filename__`\n```\n\n\nThe second syntax may lead to wrong highlighting when using a markdown editor.\nIf it happens, use the first syntax.\nAlso make sure that there are no circular includes.\n\n\nThe `!include` command also supports options:\n\n```\n!include`\u003ckey1\u003e=\u003cvalue1\u003e, \u003ckey2\u003e=\u003cvalue2\u003e` some_file\n```\n\nFor example, to specify line ranges in options:\n\n```\n!include`startLine=1, endLine=10` some_file\n```\n\nOr to include snippets with enclosed delimiters:\n\n```\n!include`snippetStart=\"\u003c!-- Start --\u003e\", snippetEnd=\"\u003c!-- End --\u003e\"` some_file\n```\n\nOr including `xml` files transforming them with `XSLT`:\n```\n!include`format=\"markdown\", xslt=\"xslt/api.xslt\"` main_8h.xml\n```\n\nwhere `\u003c!-- Start --\u003e` and `\u003c!-- End --\u003e` are two strings occuring in `some_file`.\n\nIf multiple occurences of `\u003c!-- Start --\u003e` or `\u003c!-- End --\u003e` are in `some_file`, then pandoc-include will include all the blocks between the delimiters.\nIf `snippetEnd` or `snippetStart` is not found or specified, it will include till the end or from the start.\n\nSupported options:\n\n| Key | Value | Description |\n| --- | ----- | ----------- |\n| startLine | `int` | Start line of include (default: 1) |\n| endLine | `int` | End line of include (default: number of the last line) |\n| snippetStart | `str` | Start delimiter of a snippet |\n| snippetEnd | `str` | End delimiter of a snippet |\n| includeSnippetDelimiters | `bool` | Whether to include the delimiters (default: `False`) |\n| incrementSection | `int` | Increment (or decrement) section levels of include |\n| dedent | `int` | Remove n leading whitespaces of each line where possible (`-1` means remove all) |\n| format | `str` | The input format of the included file (see `pandoc --list-input-formats`). It will be automatically deduced from the path if not set. (Hint: extensions can also be enabled here) |\n| raw | `str` | Include as raw block. The arg is the format (`latex`, `html`...) |\n| xslt | `str` | `XSLT` file to use for transforming the given `.xml` file (This is intended to be used with Doxygen's `xml` output |\n\n**Note**: the values above are parsed as Python literals. So `str` should be quoted like `'xxx'` or `\"xxx\"`; `bool` should be `True` or `False`.\n\n\n### Header options\n\n```\n---\ninclude-entry: '\u003cpath\u003e'\ninclude-order: 'natural'\ninclude-resources: '\u003cpath\u003e[:\u003cpath\u003e]'\nrewrite-path: true\npandoc-options:\n  - --filter=pandoc-include\n  - \u003cother options\u003e\n---\n```\n\n#### `include-entry`\n\nThe `include-entry` option is to make recursive includes work.\nIts value is a path relative to current working directory or absolute\nwhere the entry file (the initial file) locates.\nIt should be placed in the entry file only, not in the included files.\nIt is optional and the default `include-entry` value is `.`.\n\nFor example, to compile a file in current directory, no header is needed:\n\n```\npandoc test.md --filter pandoc-include -o test.pdf\n```\n\nHowever, to compile a file not in current directory, like:\n\n```\npandoc dir/test.md --filter pandoc-include -o test.pdf\n```\n\nThe header should now be set to: `include-entry: 'dir'`.\n\n\n#### `include-order`\n\nThe `include-order` options is to define the order of included files if the unix-style pathname matches multiple files.\nThe default value is `natural`, which means using the [natural order](https://en.wikipedia.org/wiki/Natural_sort_order).\nOther possible values are `alphabetical` and `default`.\nThe `default` means to keep the order returned by the Python `glob` module.\n\n\n#### `include-resources`\nThe `include-resources` can be used to simplify relative paths of include statements by searching in the given paths for files with relative paths when otherwise not found.\n\nGiven following directory structure and `pandoc` command:\n\n```\nmain.md\nexamples/\n    hello-world.c\ncontent/\n    chapter1/\n        chapter01.md\n        image.png\n    chapter2/\n        chapter02.md\n        image.png\n```\n```\n$ pandoc --metadata include-resources=examples/ ... main.md\n```\n\nThis will make it possible to have following include line in `chapter01.md` and `chapter02.md`\n````markdown\n```cpp\n!include hello-world.c\n```\n````\n\nInstead of:\n````markdown\n```cpp\n!include ../../examples/hello-world.c\n```\n````\n\nThis is most useful if some resources, e.g. source code or Doxygen output,\nis located in an external directory structure.\n\n\n#### `rewrite-path`\n\nThe `rewrite-path` option is a boolean value to configure whether the relative paths of images should be rewritten to paths relative to the root file.\nThe default value is `true`.\n\nFor example, consider the following directory structure:\n\n```\nmain.md\ncontent/\n  chapter01.md\n  image.png\n```\n\nSuppose `chapter01.md` uses the image `image.png`.\nIt should use `![Image](image.png)` if `rewrite-path` is `true`,\nor `![Image](content/image.png)` if `rewrite-path` is `false`.\n\n#### `pandoc-options`\n\nThe `pandoc-options` option is **a list** to specify the pandoc options when recursively processing included files.\nBy default, the included file will **inherit** the `pandoc-options` from its parent file, **unless** specified in its own file.\n\nTo make the recursive includes work, `--filter=pandoc-include` is **necessary**.\nThe default value of `pandoc-options` is:\n\n```\npandoc-options:\n  - --filter=pandoc-include\n```\n\n\n## Examples\n\n### File include\n\nFile include can be used to separate chapters into different files,\nor include some latex files:\n\n```markdown\n\n---\ntitle: Article\nauthor: Author\ntoc: true\n---\n\n!include chapters/chap01.md\n\n!include chapters/chap02.md\n\n!include chapters/chap03.md\n\n!include`raw=\"latex\"` data/table.tex\n\n```\n\n### Header include\n\nFor header include, it is useful to define a header template\nand include it in many files.\n\nFor example, in the `header.yaml`, we can define basic info:\n\n```yaml\nname: xxx\nschool: yyy\nemail: zzz\n```\n\nIn the `main.md`, we can extend the header:\n\n```markdown\n\n---\ntitle: Title\n---\n\n!include-header header.yaml\n\n# Section\n\nBody\n\n```\n\nThe `main.md` then is equivalent to the follow markdown:\n\n```markdown\n\n---\ntitle: Title\nname: xxx\nschool: yyy\nemail: zzz\n---\n\n# Section\n\nBody\n\n```\n\n\n### Environment Variables\n\nThe following environment variables can be set to change the default behaviour:\n\n| Key                            | Value      | Description                                  |\n|--------------------------------|------------|----------------------------------------------|\n| PANDOC_INCLUDE_NOT_FOUND_ERROR | `0` or `1` | Emit an error if file not found (default: 0) |\n\n\n## Development\n\nTo setup local dev environment, you can use python `venv` to create a virtual environment from `requirements.txt`.\n\nOr if you use Nix, you can simply run `nix develop`.\n\n\n## Contributing\n\nContributions are welcome if you find any bugs or want to add some features.\nPlease open an issue for discussion first if it's a big change (e.g. a new feature) or if you are uncertain about it.\n\nPlease follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)\nfor your commit messages so that the changelog can be generated automatically.\n\n\n## Trouble Shooting\n\n### Command-line options\n\nThe pandoc command-line options are processed in order.\nIf you want some options to be applied in included files,\nmake sure the `--filter pandoc-include` option is specified before those options.\n\nFor example, use bibliography in the included files:\n\n```\npandoc main.md --filter pandoc-include --citeproc --bibliography=ref.bib -o main.pdf\n```\n\n### Executable not found\n\nFor some operating systems, the path may not be set correctly after installation.\nMake sure that the `pandoc-include` executable is put in the directory which is in **the PATH environment**.\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcsunset%2Fpandoc-include","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdcsunset%2Fpandoc-include","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdcsunset%2Fpandoc-include/lists"}