<div align="center">
<strong>
<samp>
[](https://badge.fury.io/py/pandoc-filter)
[](https://pypi.org/project/pandoc-filter)
[](https://zenodo.org/doi/10.5281/zenodo.10528322)
[](https://github.com/Zhaopudark/pandoc-filter?tab=GPL-3.0-1-ov-file#readme)
[](https://github.com/Zhaopudark/pandoc-filter/actions/workflows/test.yml)
[](https://github.com/Zhaopudark/pandoc-filter/actions/workflows/build_and_deploy.yml)
[](https://github.com/Zhaopudark/pandoc-filter/actions/workflows/post_deploy_test.yml)
[](https://codecov.io/gh/Zhaopudark/pandoc-filter)
</samp>
</strong>
</div>
# pandoc-filter
This project supports some useful and highly customized [pandoc python filters](https://pandoc.org/filters.html) that based on [panflute](http://scorreia.com/software/panflute/). They can meet some special requests when using [pandoc](https://pandoc.org) to
- [x] convert files from `markdown` to `gfm`
- [x] convert files from `markdown` to `html`
- [ ] convert other formats (In the future)
Please see [Main Features](#main-features) for the concrete features.
Please see [Samples](#Samples) for the recommend usage.
# Backgrounds
I'm used to taking notes with markdown and clean markdown syntax. Then, I usually post these notes on [my site](https://little-train.com/) as web pages. So, I need to convert markdown to html. There were many tools to achieve the converting and I chose [pandoc](https://pandoc.org) at last due to its powerful features.
But sometimes, I need many more features when converting from `markdown` to `html`, where pandoc filters are needed. I have written some pandoc python filters with some advanced features by [panflute](https://github.com/sergiocorreia/panflute) and many other tools. And now, I think it's time to gather these filters into a combined toolset as this project.
# Installation
```
pip install -i https://pypi.org/simple/ -U pandoc-filter
```
# Main Features
There are 2 supported ways:
- **command-line-mode**: use non-parametric filters in command-lines with [pandoc](https://pandoc.org).
- **python-mode**: use `run_filters_pyio` function in python.
For an example, `md2md_enhance_equation_filter` in [enhance_equation.py](https://github.com/Zhaopudark/pandoc-filter/blob/main/src/pandoc_filter/filters/md2md/enhance_equation.py) is a filter function as [panflute-user-guide ](http://scorreia.com/software/panflute/guide.html). And its registered command-line script is `md2md-enhance-equation-filter`.
- So, after the installation, one can use it in **command-line-mode**:
```powershell
pandoc ./input.md -o ./output.md -f markdown -t gfm -s --filter md2md-enhance-equation-filter
```
- Or, use in **python mode**
```python
import pandoc_filter
file_path = pathlib.Path("./input.md")
output_path = pathlib.Path("./output.md")
pandoc_filter.run_filters_pyio(file_path,output_path,'markdown','gfm',[pandoc_filter.md2md_enhance_equation_filter])
```
**Runtime status** can be recorded. In **python mode**, any filter function will return a proposed panflute `Doc`. Some filter functions will add an instance attribute dict `runtime_dict` to the returned `Doc`, as a record for **runtime status**, which may be very useful for advanced users. For an example, `md2md_enhance_equation_filter`, will add an instance attribute dict `runtime_dict` to the returned `Doc`, which may contain a mapping `{'math':True}` if there is any math element in the `Doc`.
All filters with corresponding registered command-line scripts, the specific features, and the recorded **runtime status** are recorded as the following:
> [!NOTE]
>
> Since some filters need additional arguments, not all filter functions support **command-line-mode**, even though they all support **python-mode** indeed.
>
> All filters support cascaded invoking.
- `pandoc_filter.filters.md2md.convert_github_style_alert_to_hexo_style_alert.run_filter`
- [source](./src/pandoc_filter/filters/md2md/convert_github_style_alert_to_hexo_style_alert.py)
- command-line: `md2md-convert-github-style-alert-to-hexo-style-alert-filter`
- main features: Convert the [github-style alert](https://github.com/orgs/community/discussions/16925) to hexo-style alert.
- `pandoc_filter.filters.md2md.enhance_equation.run_filter`
- [source](./src/pandoc_filter/filters/md2md/enhance_equation.py)
- command-line: `md2md-enhance-equation-filter`
- main features: Enhance math equations.
- Runtime status (`doc.runtime_dict`): ` {'math':< bool >,'equations_count':<some_number>}`
- `pandoc_filter.filters.md2md.norm_footnote.run_filter`
- [source](./src/pandoc_filter/filters/md2md/norm_internal_link.py)
- command-line: `md2md-norm-footnote-filter`
- main features: Normalize the footnotes.
- `pandoc_filter.filters.md2md.norm_internal_link.run_filter`
- [source](./src/pandoc_filter/filters/md2md/norm_internal_link.py)
- command-line: ` md2md-norm-internal-link-filter`
- main features: Normalize internal links' URLs.
- `pandoc_filter.filters.md2md.upload_figure_to_aliyun.run_filter`
- [source](./src/pandoc_filter/filters/md2md/upload_figure_to_aliyun.py)
- command-line: ==Unsupported.==
- Additional Arguments: `doc_path`
- main features: Auto upload local pictures to Aliyun OSS.
- Runtime status (`doc.runtime_dict`): {'doc_path':<doc_path>,'oss_helper':<Oss_Helper>}
- `pandoc_filter.filters.md2html.centralize_figure.run_filter`
- [source](./src/pandoc_filter/filters/md2html/centralize_figure.py)
- command-line: `md2html-centralize-figure-filter`
- main features: ==Deprecated==
- `pandoc_filter.filters.md2html.enhance_footnote.run_filter`
- [source](./src/pandoc_filter/filters/md2html/enhance_footnote.py)
- command-line: `md2html-enhance-footnote-filter`
- main features: Enhance the footnote.
- `pandoc_filter.filters.md2html.enhance_link_like.run_filter`
- [source](./src/pandoc_filter/filters/md2html/enhance_link_like.py)
- command-line: `md2html-enhance-link-like-filter`
- main features: Enhance the link-like string to a `link` element.
- `pandoc_filter.filters.md2html.hash_anchor_and_internal_link.run_filter`
- [source](./src/pandoc_filter/filters/md2html/hash_anchor_and_internal_link.py)
- command-line: `md2html-hash-anchor-and-internal-link-filter`
- main features: Hash both the anchor's `id` and the internal-link's `url ` simultaneously.
- Runtime status (`doc.runtime_dict`): `{'anchor_count':<anchor_count_dict>,'internal_link_record':<internal_link_record_list>}`
- `pandoc_filter.filters.md2html.increase_header_level.run_filter`
- [source](./src/pandoc_filter/filters/md2html/increase_header_level.py)
- command-line: `md2html-increase-header-level-filter`
- main features: Increase the header level by `1`.
# Samples
Here are 2 basic types of examples
## Convert markdown to markdown (Normalization)
- [Adapt AMS rule for math formula](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_adapt_ams_rule_for_math_formula.md)
- [Convert Github style alert to Hexo style alert](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_convert_github_style_alert_to_hexo_style_alert_filter.md)
- [Normalize footnotes](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_normalize_footnotes.md)
- [Normalize internal link](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_normalize_internal_link.md)
- [Sync local images to `Aliyun OSS`](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_sync_local_images_to_`Aliyun_OSS`.md)
## Convert markdown to html
- [Normalize headers, anchors, internal links and link-like strings](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2html_normalize_headers_anchors_internal_links_and_link-like_strings.md)
# Contribution
Contributions are welcome. But recently, the introduction and documentation are not complete. So, please wait for a while.
A simple way to contribute is to open an issue to report bugs or request new features.
Raw data
{
"_id": null,
"home_page": null,
"name": "pandoc-filter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "pandoc, pandoc-filter, python, pandoc-python-filter, markdown, html",
"author": null,
"author_email": "Pu Zhao <zhaopudark@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/50/f8/fcbd0c8afdae47309ea98030a9f8b58d3ec89065499c7adadf3dcfe1789b/pandoc_filter-0.2.15.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<strong>\n<samp>\n\n[](https://badge.fury.io/py/pandoc-filter)\n[](https://pypi.org/project/pandoc-filter)\n[](https://zenodo.org/doi/10.5281/zenodo.10528322)\n[](https://github.com/Zhaopudark/pandoc-filter?tab=GPL-3.0-1-ov-file#readme)\n\n[](https://github.com/Zhaopudark/pandoc-filter/actions/workflows/test.yml)\n[](https://github.com/Zhaopudark/pandoc-filter/actions/workflows/build_and_deploy.yml)\n[](https://github.com/Zhaopudark/pandoc-filter/actions/workflows/post_deploy_test.yml)\n[](https://codecov.io/gh/Zhaopudark/pandoc-filter)\n\n</samp>\n</strong>\n</div>\n\n# pandoc-filter\n\nThis project supports some useful and highly customized [pandoc python filters](https://pandoc.org/filters.html) that based on [panflute](http://scorreia.com/software/panflute/). They can meet some special requests when using [pandoc](https://pandoc.org) to\n\n- [x] convert files from `markdown` to `gfm`\n- [x] convert files from `markdown` to `html`\n- [ ] convert other formats (In the future)\n\nPlease see [Main Features](#main-features) for the concrete features.\n\nPlease see [Samples](#Samples) for the recommend usage.\n\n# Backgrounds\n\nI'm used to taking notes with markdown and clean markdown syntax. Then, I usually post these notes on [my site](https://little-train.com/) as web pages. So, I need to convert markdown to html. There were many tools to achieve the converting and I chose [pandoc](https://pandoc.org) at last due to its powerful features.\n\nBut sometimes, I need many more features when converting from `markdown` to `html`, where pandoc filters are needed. I have written some pandoc python filters with some advanced features by [panflute](https://github.com/sergiocorreia/panflute) and many other tools. And now, I think it's time to gather these filters into a combined toolset as this project. \n\n# Installation\n\n```\npip install -i https://pypi.org/simple/ -U pandoc-filter\n```\n\n# Main Features\n\nThere are 2 supported ways:\n\n- **command-line-mode**: use non-parametric filters in command-lines with [pandoc](https://pandoc.org).\n- **python-mode**: use `run_filters_pyio` function in python.\n\nFor an example, `md2md_enhance_equation_filter` in [enhance_equation.py](https://github.com/Zhaopudark/pandoc-filter/blob/main/src/pandoc_filter/filters/md2md/enhance_equation.py) is a filter function as [panflute-user-guide ](http://scorreia.com/software/panflute/guide.html). And its registered command-line script is `md2md-enhance-equation-filter`. \n\n- So, after the installation, one can use it in **command-line-mode**:\n\n ```powershell\n pandoc ./input.md -o ./output.md -f markdown -t gfm -s --filter md2md-enhance-equation-filter\n ```\n\n- Or, use in **python mode**\n\n ```python\n import pandoc_filter\n file_path = pathlib.Path(\"./input.md\")\n output_path = pathlib.Path(\"./output.md\")\n pandoc_filter.run_filters_pyio(file_path,output_path,'markdown','gfm',[pandoc_filter.md2md_enhance_equation_filter])\n ```\n\n**Runtime status** can be recorded. In **python mode**, any filter function will return a proposed panflute `Doc`. Some filter functions will add an instance attribute dict `runtime_dict` to the returned `Doc`, as a record for **runtime status**, which may be very useful for advanced users. For an example, `md2md_enhance_equation_filter`, will add an instance attribute dict `runtime_dict` to the returned `Doc`, which may contain a mapping `{'math':True}` if there is any math element in the `Doc`.\n\nAll filters with corresponding registered command-line scripts, the specific features, and the recorded **runtime status** are recorded as the following:\n\n> [!NOTE]\n>\n> Since some filters need additional arguments, not all filter functions support **command-line-mode**, even though they all support **python-mode** indeed.\n>\n> All filters support cascaded invoking.\n\n- `pandoc_filter.filters.md2md.convert_github_style_alert_to_hexo_style_alert.run_filter`\n - [source](./src/pandoc_filter/filters/md2md/convert_github_style_alert_to_hexo_style_alert.py)\n - command-line: `md2md-convert-github-style-alert-to-hexo-style-alert-filter`\n - main features: Convert the [github-style alert](https://github.com/orgs/community/discussions/16925) to hexo-style alert.\n- `pandoc_filter.filters.md2md.enhance_equation.run_filter`\n - [source](./src/pandoc_filter/filters/md2md/enhance_equation.py)\n - command-line: `md2md-enhance-equation-filter`\n - main features: Enhance math equations.\n - Runtime status (`doc.runtime_dict`): ` {'math':< bool >,'equations_count':<some_number>}`\n- `pandoc_filter.filters.md2md.norm_footnote.run_filter`\n - [source](./src/pandoc_filter/filters/md2md/norm_internal_link.py)\n - command-line: `md2md-norm-footnote-filter`\n - main features: Normalize the footnotes.\n- `pandoc_filter.filters.md2md.norm_internal_link.run_filter`\n - [source](./src/pandoc_filter/filters/md2md/norm_internal_link.py)\n - command-line: ` md2md-norm-internal-link-filter`\n - main features: Normalize internal links' URLs.\n- `pandoc_filter.filters.md2md.upload_figure_to_aliyun.run_filter`\n - [source](./src/pandoc_filter/filters/md2md/upload_figure_to_aliyun.py)\n - command-line: ==Unsupported.==\n - Additional Arguments: `doc_path`\n - main features: Auto upload local pictures to Aliyun OSS.\n - Runtime status (`doc.runtime_dict`): {'doc_path':<doc_path>,'oss_helper':<Oss_Helper>}\n- `pandoc_filter.filters.md2html.centralize_figure.run_filter`\n - [source](./src/pandoc_filter/filters/md2html/centralize_figure.py)\n - command-line: `md2html-centralize-figure-filter`\n - main features: ==Deprecated==\n- `pandoc_filter.filters.md2html.enhance_footnote.run_filter`\n - [source](./src/pandoc_filter/filters/md2html/enhance_footnote.py)\n - command-line: `md2html-enhance-footnote-filter`\n - main features: Enhance the footnote.\n- `pandoc_filter.filters.md2html.enhance_link_like.run_filter`\n - [source](./src/pandoc_filter/filters/md2html/enhance_link_like.py)\n - command-line: `md2html-enhance-link-like-filter`\n - main features: Enhance the link-like string to a `link` element.\n- `pandoc_filter.filters.md2html.hash_anchor_and_internal_link.run_filter`\n - [source](./src/pandoc_filter/filters/md2html/hash_anchor_and_internal_link.py)\n - command-line: `md2html-hash-anchor-and-internal-link-filter`\n - main features: Hash both the anchor's `id` and the internal-link's `url ` simultaneously.\n - Runtime status (`doc.runtime_dict`): `{'anchor_count':<anchor_count_dict>,'internal_link_record':<internal_link_record_list>}`\n- `pandoc_filter.filters.md2html.increase_header_level.run_filter`\n - [source](./src/pandoc_filter/filters/md2html/increase_header_level.py)\n - command-line: `md2html-increase-header-level-filter`\n - main features: Increase the header level by `1`.\n\n# Samples\n\nHere are 2 basic types of examples\n\n## Convert markdown to markdown (Normalization)\n\n- [Adapt AMS rule for math formula](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_adapt_ams_rule_for_math_formula.md)\n- [Convert Github style alert to Hexo style alert](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_convert_github_style_alert_to_hexo_style_alert_filter.md)\n- [Normalize footnotes](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_normalize_footnotes.md)\n- [Normalize internal link](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_normalize_internal_link.md)\n- [Sync local images to `Aliyun OSS`](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2md_sync_local_images_to_`Aliyun_OSS`.md)\n\n## Convert markdown to html\n\n- [Normalize headers, anchors, internal links and link-like strings](https://github.com/Zhaopudark/pandoc-filter/blob/main/examples/md2html_normalize_headers_anchors_internal_links_and_link-like_strings.md)\n\n\n# Contribution\n\nContributions are welcome. But recently, the introduction and documentation are not complete. So, please wait for a while.\n\nA simple way to contribute is to open an issue to report bugs or request new features.\n\n\n\n",
"bugtrack_url": null,
"license": "GNU General Public License (GPL)",
"summary": "A customized pandoc filters set that can be used to generate a useful pandoc python filter.",
"version": "0.2.15",
"project_urls": {
"Changelog": "https://github.com/Zhaopudark/pandoc-filter/blob/main/RELEASE.md",
"Documentation": "https://github.com/Zhaopudark/pandoc-filter/blob/main/README.md",
"Homepage": "https://github.com/Zhaopudark/pandoc-filter",
"Issues": "https://github.com/Zhaopudark/pandoc-filter/issues",
"Repository": "https://github.com/Zhaopudark/pandoc-filter.git"
},
"split_keywords": [
"pandoc",
" pandoc-filter",
" python",
" pandoc-python-filter",
" markdown",
" html"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7183f6c58a3fa335e57470704bc1b95b46315f11e20978f059a27d8077f4179b",
"md5": "6c0f2f292bbf94fa95514ba64f915ab7",
"sha256": "0e373ff86c5945a2f9b72a2e4bcb1317b7639fee97f18d0dccf320d2c2efa06f"
},
"downloads": -1,
"filename": "pandoc_filter-0.2.15-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6c0f2f292bbf94fa95514ba64f915ab7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 37017,
"upload_time": "2024-05-24T05:23:31",
"upload_time_iso_8601": "2024-05-24T05:23:31.734395Z",
"url": "https://files.pythonhosted.org/packages/71/83/f6c58a3fa335e57470704bc1b95b46315f11e20978f059a27d8077f4179b/pandoc_filter-0.2.15-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50f8fcbd0c8afdae47309ea98030a9f8b58d3ec89065499c7adadf3dcfe1789b",
"md5": "6a4f01fd42898d9fc5581a511ef59bed",
"sha256": "dcbee6af651f94d9c814b3a3b4b970c098fc9e87b02d1885541866152adb7d23"
},
"downloads": -1,
"filename": "pandoc_filter-0.2.15.tar.gz",
"has_sig": false,
"md5_digest": "6a4f01fd42898d9fc5581a511ef59bed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 32757,
"upload_time": "2024-05-24T05:23:33",
"upload_time_iso_8601": "2024-05-24T05:23:33.092134Z",
"url": "https://files.pythonhosted.org/packages/50/f8/fcbd0c8afdae47309ea98030a9f8b58d3ec89065499c7adadf3dcfe1789b/pandoc_filter-0.2.15.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-24 05:23:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Zhaopudark",
"github_project": "pandoc-filter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pandoc-filter"
}
JSON
