This project supports some useful and highly customized pandoc python filters that based on panflute. They can meet some special requests when using pandoc to
- convert files from
markdown
togfm
- convert files from
markdown
tohtml
- convert other formats (In the future)
Please see Main Features for the concrete features.
Please see Samples for the recommend usage.
I'm used to taking notes with markdown and clean markdown syntax. Then, I usually post these notes on my site as web pages. So, I need to convert markdown to html. There were many tools to achieve the converting and I chose pandoc 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 and many other tools. And now, I think it's time to gather these filters into a combined toolset as this project.
pip install -i https://pypi.org/simple/ -U pandoc-filter
There are 2 supported ways:
- command-line-mode: use non-parametric filters in command-lines with pandoc.
- python-mode: use
run_filters_pyio
function in python.
For an example, md2md_enhance_equation_filter
in enhance_equation.py is a filter function as panflute-user-guide . And its registered command-line script is md2md-enhance-equation-filter
.
-
So, after the installation, one can use it in command-line-mode:
pandoc ./input.md -o ./output.md -f markdown -t gfm -s --filter md2md-enhance-equation-filter
-
Or, use in python mode
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
- command-line:
md2md-convert-github-style-alert-to-hexo-style-alert-filter
- main features: Convert the github-style alert to hexo-style alert.
pandoc_filter.filters.md2md.enhance_equation.run_filter
- source
- 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
- command-line:
md2md-norm-footnote-filter
- main features: Normalize the footnotes.
pandoc_filter.filters.md2md.norm_internal_link.run_filter
- source
- command-line:
md2md-norm-internal-link-filter
- main features: Normalize internal links' URLs.
pandoc_filter.filters.md2md.upload_figure_to_aliyun.run_filter
- source
- 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
- command-line:
md2html-centralize-figure-filter
- main features: ==Deprecated==
pandoc_filter.filters.md2html.enhance_footnote.run_filter
- source
- command-line:
md2html-enhance-footnote-filter
- main features: Enhance the footnote.
pandoc_filter.filters.md2html.enhance_link_like.run_filter
- source
- 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
- command-line:
md2html-hash-anchor-and-internal-link-filter
- main features: Hash both the anchor's
id
and the internal-link'surl
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
- command-line:
md2html-increase-header-level-filter
- main features: Increase the header level by
1
.
Here are 2 basic types of examples
- Adapt AMS rule for math formula
- Convert Github style alert to Hexo style alert
- Normalize footnotes
- Normalize internal link
- Sync local images to
Aliyun OSS
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.