{"id":13440764,"url":"https://github.com/tomduck/pandoc-eqnos","last_synced_at":"2025-05-15T06:15:13.124Z","repository":{"id":28760256,"uuid":"32282413","full_name":"tomduck/pandoc-eqnos","owner":"tomduck","description":"A pandoc filter for numbering equations and equation references.","archived":false,"fork":false,"pushed_at":"2022-04-11T08:57:11.000Z","size":998,"stargazers_count":224,"open_issues_count":13,"forks_count":27,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-15T19:50:26.079Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tomduck.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-15T20:30:17.000Z","updated_at":"2025-02-15T16:32:48.000Z","dependencies_parsed_at":"2022-08-25T20:30:36.959Z","dependency_job_id":null,"html_url":"https://github.com/tomduck/pandoc-eqnos","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomduck%2Fpandoc-eqnos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomduck%2Fpandoc-eqnos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomduck%2Fpandoc-eqnos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomduck%2Fpandoc-eqnos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomduck","download_url":"https://codeload.github.com/tomduck/pandoc-eqnos/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283188,"owners_count":22045141,"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":[],"created_at":"2024-07-31T03:01:25.939Z","updated_at":"2025-05-15T06:15:13.079Z","avatar_url":"https://github.com/tomduck.png","language":"Python","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"\n\n**New in 2.5.0:** Allow reference numbers to be set in brackets ([Issue #57](https://github.com/tomduck/pandoc-eqnos/issues/57)).\n\n**New in 2.4.0:** Updated to work with pandoc 2.11.\n\n[more...](#whats-new)\n\n\npandoc-eqnos 2.5.0\n==================\n\n*pandoc-eqnos* is a [pandoc] filter for numbering equations and their references when converting markdown to other formats.  It is part of the [pandoc-xnos] filter suite.  LaTeX/pdf, html, and epub output have native support.  Native support for docx output is a work in progress.\n\nDemonstration: Processing [demo3.md] with pandoc + pandoc-eqnos gives numbered equations and references in [pdf][pdf3], [tex][tex3], [html][html3], [epub][epub3], [docx][docx3] and other formats (including beamer slideshows).\n\nThis version of pandoc-eqnos was tested using pandoc 1.15.2 - 2.11.1.1,\u003csup\u003e[1](#footnote1)\u003c/sup\u003e and may be used with linux, macOS, and Windows. Bug reports and feature requests may be posted on the project's [Issues tracker].  If you find pandoc-eqnos useful, then please kindly give it a star [on GitHub].\n\nSee also: [pandoc-fignos], [pandoc-tablenos], [pandoc-secnos] \\\nOther filters: [pandoc-comments], [pandoc-latex-extensions]\n\n[pandoc]: http://pandoc.org/\n[pandoc-xnos]: https://github.com/tomduck/pandoc-xnos\n[Issues tracker]: https://github.com/tomduck/pandoc-eqnos/issues\n[on GitHub]:  https://github.com/tomduck/pandoc-eqnos\n[pandoc-fignos]: https://github.com/tomduck/pandoc-fignos\n[pandoc-tablenos]: https://github.com/tomduck/pandoc-tablenos\n[pandoc-secnos]: https://github.com/tomduck/pandoc-secnos\n[pandoc-comments]: https://github.com/tomduck/pandoc-comments\n[pandoc-latex-extensions]: https://github.com/tomduck/pandoc-latex-extensions\n\n\nContents\n--------\n\n 1. [Installation](#installation)\n 2. [Usage](#usage)\n 3. [Markdown Syntax](#markdown-syntax)\n 4. [Customization](#customization)\n 5. [Technical Details](#technical-details)\n 6. [Getting Help](#getting-help)\n 7. [Development](#development)\n 8. [What's New](#whats-new)\n\n\nInstallation\n------------\n\nPandoc-eqnos requires [python].  It is easily installed -- see [here](https://realpython.com/installing-python/).\u003csup\u003e[2](#footnote2)\u003c/sup\u003e  Either python 2.7 or 3.x will do.\n\nPandoc-eqnos may be installed using the shell command\n\n    pip install pandoc-eqnos --user\n\nand upgraded by appending `--upgrade` to the above command.  Pip is a program that downloads and installs software from the Python Package Index, [PyPI].  It normally comes installed with a python distribution.\u003csup\u003e[3](#footnote3)\u003c/sup\u003e\n\nInstructions for installing from source are given in [DEVELOPERS.md].\n\n[python]: https://www.python.org/\n[PyPI]: https://pypi.python.org/pypi\n[DEVELOPERS.md]: DEVELOPERS.md\n\n\nUsage\n-----\n\nPandoc-eqnos is activated by using the\n\n    --filter pandoc-eqnos\n\noption with pandoc.  Alternatively, use\n\n    --filter pandoc-xnos\n\nto activate all of the filters in the [pandoc-xnos] suite (if installed).\n\nAny use of `--filter pandoc-citeproc` or `--bibliography=FILE` should come *after* the `pandoc-eqnos` or `pandoc-xnos` filter calls.\n\n\nMarkdown Syntax\n---------------\n\nThe cross-referencing syntax used by pandoc-eqnos was developed in [pandoc Issue #813] -- see [this post] by [@scaramouche1].\n\nTo mark an equation for numbering, add an identifier to its attributes:\n\n    $$ y = mx + b $$ {#eq:id}\n\nThe prefix `#eq:` is required. `id` should be replaced with a unique string composed of letters, numbers, dashes and underscores.  If `id` is omitted then the equation will be numbered but unreferenceable.\n\nTo reference the equation, use\n\n    @eq:id\n\nor\n\n    {@eq:id}\n\nCurly braces protect a reference and are stripped from the output.\n\nDemonstration: Processing [demo.md] with pandoc + pandoc-eqnos gives numbered equations and references in [pdf], [tex], [html], [epub], [docx] and other formats.\n\n[pandoc Issue #813]: https://github.com/jgm/pandoc/issues/813\n[this post]: https://github.com/jgm/pandoc/issues/813#issuecomment-70423503\n[@scaramouche1]: https://github.com/scaramouche1\n[demo.md]: https://raw.githubusercontent.com/tomduck/pandoc-eqnos/master/demos/demo.md\n[pdf]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo.pdf\n[tex]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo.tex\n[html]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo.html\n[epub]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo.epub\n[docx]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo.docx\n\n\n### Clever References ###\n\nWriting markdown like\n\n    See eq. @eq:id.\n\nseems a bit redundant.  Pandoc-eqnos supports \"clever references\" via single-character modifiers in front of a reference.  You can write\n\n     See +@eq:id.\n\nto have the reference name (i.e., \"eq.\") automatically generated.  The above form is used mid-sentence; at the beginning of a sentence, use\n\n     *@eq:id\n\ninstead.  If clever references are enabled by default (see [Customization](#customization), below), then users may disable it for a given reference using\u003csup\u003e[4](#footnote4)\u003c/sup\u003e\n\n    !@eq:id\n\nDemonstration: Processing [demo2.md] with pandoc + pandoc-eqnos gives numbered equations and references in [pdf][pdf2], [tex][tex2], [html][html2], [epub][epub2], [docx][docx2] and other formats.\n\nNote: When using `*@eq:id` and emphasis (e.g., `*italics*`) in the same sentence, the `*` in the clever reference must be backslash-escaped; i.e., `\\*@eq:id`.\n\n[demo2.md]: https://raw.githubusercontent.com/tomduck/pandoc-eqnos/master/demos/demo2.md\n[pdf2]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo2.pdf\n[tex2]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo2.tex\n[html2]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo2.html\n[epub2]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo2.epub\n[docx2]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo2.docx\n\n\n### Tagged Equations ###\n\nThe equation number may be overridden by placing a tag in the equation's attributes block:\n\n    $$ y = mx + b $$ {#eq:id tag=\"B.1\"}\n\nThe tag may be arbitrary text, or an inline equation such as `$\\mathrm{B.1'}$`.  Mixtures of the two are not currently supported.\n\n\n### Disabling Links ###\n\nTo disable a link on a reference, set `nolink=True` in the reference's attributes:\n\n    @eq:id{nolink=True}\n\n\nCustomization\n-------------\n\nPandoc-eqnos may be customized by setting variables in the [metadata block] or on the command line (using `-M KEY=VAL`).  The following variables are supported:\n\n  * `eqnos-warning-level` or `xnos-warning-level` - Set to `0` for\n    no warnings, `1` for critical warnings, or `2` (default) for\n    all warnings.  Warning level 2 should be used when\n    troubleshooting.\n\n  * `eqnos-cleveref` or `xnos-cleveref` - Set to `True` to assume \"+\"\n    clever references by default;\n\n  * `xnos-capitalise` - Capitalises the names of \"+\" clever\n    references (e.g., change from \"fig.\" to \"Fig.\");\n\n  * `eqnos-plus-name` - Sets the name of a \"+\" clever reference \n    (e.g., change it from \"eq.\" to \"equation\"). Settings here take\n    precedence over `xnos-capitalise`;\n\n  * `eqnos-star-name` - Sets the name of a \"*\" clever reference \n    (e.g., change it from \"Equation\" to \"Eq.\");\n\n  * `eqnos-eqref` - Set to `True` to use AMS-style equation references\n     (i.e., equation numbers set in brackets); and\n\n  * `eqnos-number-by-section` or `xnos-number-by-section` - Set to\n    `True` to number equations by section (e.g., Eq. 1.1, 1.2, etc in\n    Section 1, and Eq. 2.1, 2.2, etc in Section 2).  For LaTeX/pdf,\n    html, and epub output, this feature should be used together with\n    pandoc's `--number-sections`\n    [option](https://pandoc.org/MANUAL.html#option--number-sections)\n    enabled.  For docx, use [docx custom styles] instead.\n\n    This option should not be set for numbering by chapter in\n    LaTeX/pdf book document classes.\n\n  * `xnos-number-offset` - Set to an integer to offset the section\n    numbers when numbering equations by section.  For html and epub\n    output, this feature should be used together with pandoc's\n    `--number-offset`\n    [option](https://pandoc.org/MANUAL.html#option--number-sections)\n    set to the same integer value.  For LaTeX/pdf, this option\n    offsets the actual section numbers as required.\n\n  * `eqnos-default-env` - Name of the default LaTeX environment\n    (default: 'equation').  See [Environments](#environments), below.\n\nNote that variables beginning with `eqnos-` apply to only pandoc-eqnos, whereas variables beginning with `xnos-` apply to all of the pandoc-fignos/eqnos/tablenos/secnos.\n\nDemonstration: Processing [demo3.md] with pandoc + pandoc-eqnos gives numbered equations and references in [pdf][pdf3], [tex][tex3], [html][html3], [epub][epub3], [docx][docx3] and other formats.\n\n[metadata block]: http://pandoc.org/README.html#extension-yaml_metadata_block\n[docx custom styles]: https://pandoc.org/MANUAL.html#custom-styles\n[demo3.md]: https://raw.githubusercontent.com/tomduck/pandoc-eqnos/master/demos/demo3.md\n[pdf3]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo3.pdf\n[tex3]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo3.tex\n[html3]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo3.html\n[epub3]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo3.epub\n[docx3]: https://raw.githack.com/tomduck/pandoc-eqnos/demos/demo3.docx\n\n\n### Environments ###\n\nThe default LaTeX environment may be overridden by adding an `env` attribute.  For example:\n\n    $$ y = mx + b $$ {#eq:id env=multline}\n\nThe `env` attribute must be a valid amsmath environment.\nIf the attribute value is of the form `X.Y`, `X` will be used\nas the name of the amsmath environment and `Y` will be used as an extra argument for the environment (e.g. the `alignat` environment expects an argument for the number of equation columns).  This customization only affects LaTeX/PDF output only.\n\n\nTechnical Details\n-----------------\n\n### LaTeX/pdf Output ###\n\nDuring processing, pandoc-eqnos inserts the packages and supporting LaTeX it needs into the `header-includes` metadata field.  To see what is inserted, set the `eqnos-warning-level` meta variable to `2`.  Note that any use of pandoc's `--include-in-header` option [overrides](https://github.com/jgm/pandoc/issues/3139) all `header-includes`.\n\nAn example reference in LaTeX looks like\n\n~~~latex\nSee \\cref{eq:polynomial}.\n~~~\n\nAn example equation looks like\n\n~~~latex\n\\begin{equation}\n  y = \\sum_{n=0}^{\\infty} a_n x^n\n  \\label{eq:polynomial}\n\\end{equation}\n~~~\n\nOther details:\n\n  * The `cleveref` package is used for clever references; \n  * The `\\label` and `\\ref` macros are used for figure labels and\n    references, respectively (`\\Cref` and `\\cref` are used for\n    clever references);\n  * Clever reference names are set with `\\Crefname` and `\\crefname`;\n  * Tagged equations make use of the `\\tag` macro;\n  * If clever referencing is enabled, then AMS-style referencing is\n    achieved by setting the `\\creflabelformat`; otherwise, the\n    amsmath `\\eqref` macro is used.\n\n\n### Html/Epub Output ###\n\nAn example reference in html looks like\n\n~~~html\nSee eq. \u003ca href=\"#eq:polynomial\"\u003e1\u003c/a\u003e.\n~~~\n\nAn example equation looks like\n\n~~~html\n\u003cdiv id=\"eq:polynomial\" class=\"eqnos\" style=\"position: relative;\n     width: 100%\"\u003e\n  \u003cspan class=\"math display\"\u003e\n    y = \\sum_{n=0}^{\\infty} a_n x^n\n  \u003c/span\u003e\n  \u003cspan style=\"position: absolute; right: 0em; top: 50%;\n        line-height:0; text-align: right\"\u003e\n    (1)\n  \u003c/span\u003e\n\u003c/div\u003e\n~~~\n\nThe equation and its number are wrapped in a `\u003cdiv\u003e\u003c/div\u003e` with an `id` for linking and with class `eqnos` to allow for css styling.  The number is in a separate span from the equation and is positioned right.\n\n\n### Docx Output ###\n\nDocx OOXML output is under development and subject to change.  Native capabilities will be used wherever possible.\n\n\nGetting Help\n------------\n\nIf you have any difficulties with pandoc-eqnos, or would like to see a new feature, then please submit a report to our [Issues tracker].\n\n\nDevelopment\n-----------\n\nPandoc-eqnos will continue to support pandoc 1.15-onward and python 2 \u0026 3 for the foreseeable future.  The reasons for this are that a) some users cannot upgrade pandoc and/or python; and b) supporting all versions tends to make pandoc-eqnos more robust.\n\nDeveloper notes are maintained in [DEVELOPERS.md].\n\n\nWhat's New\n----------\n\n**New in 2.5.0:** Allow reference numbers to be set in brackets ([Issue #57](https://github.com/tomduck/pandoc-eqnos/issues/57)).\n\n**New in 2.4.0:** Updated to work with pandoc 2.11.\n\n**New in 2.3.0:** Allow LaTeX equation environment customization ([Pull Request #44](https://github.com/tomduck/pandoc-eqnos/pull/44)).\n\n**New in 2.2.3:** Fixed XHTML Transitional validation error ([Issue #50](https://github.com/tomduck/pandoc-eqnos/issues/50)).\n\n**New in 2.2.1:** Updated for pandoc 2.10.1.\n\n**New in 2.1.1:** Warnings are now given for duplicate reference targets.\n\n**New in 2.0.0:**  This version represents a major revision of pandoc-eqnos.  While the interface is similar to that of the 1.x series, some users may encounter minor compatibility issues.\n\nWarning messages are a new feature of pandoc-eqnos.  The meta variable `eqnos-warning-level` may be set to `0`, `1`, or `2` depending on the degree of warnings desired.  Warning level `1` will alert users to bad references, malformed attributes, and unknown meta variables.  Warning level `2` (the default) adds informational messages that should be helpful with debugging.  Level `0` turns all messages off.\n\nMeta variable names have been updated.  Deprecated names have been removed, and new variables have been added.  Note in particular that the `eqnos-number-sections` and `xnos-number-sections` variables have been renamed to `eqnos-number-by-section` and `xnos-number-by-section`, respectively.\n\nThe basic filter and library codes have been refactored and improved with a view toward maintainability.  While extensive tests have been performed, some problems may have slipped through unnoticed.  Bug reports should be submitted to our [Issues tracker].\n\n\n*LaTeX/PDF:*\n\nLaTeX codes produced by pandoc-eqnos are massively improved.  The hacks used before were causing some users problems.  The new approach provides more flexibility and better compatibility with the LaTeX system.\n\nSupporting LaTeX is now written to the `header-includes` meta data.  Users no longer need to include LaTeX commands in the `header-includes` to get basic pandoc-eqnos functions to work.  Use `eqnos-warning-level: 2` to see what pandoc-eqnos adds to the `header-includes`.\n\nA word of warning: Pandoc-eqnos's additions to the `header-includes` are overridden when pandoc's `--include-in-header` option is used.  This is owing to a [design choice](https://github.com/jgm/pandoc/issues/3139) in pandoc.  Users may choose to deliberately override pandoc-eqnos's `header-includes` by providing their own LaTeX through `--include-in-header`.  If a user needs to include other bits of LaTeX in this way, then they will need to do the same for the LaTeX that pandoc-eqnos needs.\n\n\n*Html/Epub:*\n\nThe equation is now enclosed in a `\u003cdiv\u003e` which contains the `id` and class `eqnos`.  This change was made to facilitate styling, and for consistency with pandoc-fignos and pandoc-tablenos.  An inline-block `\u003cspan\u003e` was formerly used instead.\n\nEpub support is generally improved.\n\n\n----\n\n**Footnotes**\n\n\u003ca name=\"footnote1\"\u003e1\u003c/a\u003e: Pandoc 2.4 [broke](https://github.com/jgm/pandoc/issues/5099) how references are parsed, and so is not supported.\n\n\u003ca name=\"footnote2\"\u003e2\u003c/a\u003e: For MacOS, my preferred install method is to use the package [available from python.org](https://www.python.org/downloads/).\n\n\u003ca name=\"footnote3\"\u003e3\u003c/a\u003e: Anaconda users may be tempted to use `conda` instead.  This is not advised.  The packages distributed on the Anaconda cloud are unofficial, are not posted by me, and in some cases are ancient.  Some tips on using `pip` in a `conda` environment may be found [here](https://www.anaconda.com/using-pip-in-a-conda-environment/).\n\n\u003ca name=\"footnote4\"\u003e4\u003c/a\u003e: The disabling modifier \"!\" is used instead of \"-\" because [pandoc drops minus signs] in front of references.\n\n[pandoc drops minus signs]: https://github.com/jgm/pandoc/issues/2901\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomduck%2Fpandoc-eqnos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomduck%2Fpandoc-eqnos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomduck%2Fpandoc-eqnos/lists"}