{"id":13425716,"url":"https://github.com/lierdakil/pandoc-crossref","last_synced_at":"2026-01-31T14:07:22.667Z","repository":{"id":29018324,"uuid":"32545539","full_name":"lierdakil/pandoc-crossref","owner":"lierdakil","description":"Pandoc filter for cross-references","archived":false,"fork":false,"pushed_at":"2025-03-23T21:38:22.000Z","size":2910,"stargazers_count":977,"open_issues_count":89,"forks_count":77,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-03T06:04:38.924Z","etag":null,"topics":["haskell","pandoc","pandoc-crossref","pandoc-filter"],"latest_commit_sha":null,"homepage":"https://lierdakil.github.io/pandoc-crossref/","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lierdakil.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":"2015-03-19T20:51:47.000Z","updated_at":"2025-04-03T02:40:30.000Z","dependencies_parsed_at":"2023-12-28T17:47:36.764Z","dependency_job_id":"96f3ebb5-cf24-46ef-9ddc-e69d239b503c","html_url":"https://github.com/lierdakil/pandoc-crossref","commit_stats":{"total_commits":891,"total_committers":23,"mean_commits":38.73913043478261,"dds":"0.029180695847362492","last_synced_commit":"86c388d20bed376e259a53279363d3413148c868"},"previous_names":[],"tags_count":146,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lierdakil%2Fpandoc-crossref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lierdakil%2Fpandoc-crossref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lierdakil%2Fpandoc-crossref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lierdakil%2Fpandoc-crossref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lierdakil","download_url":"https://codeload.github.com/lierdakil/pandoc-crossref/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248202090,"owners_count":21064261,"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":["haskell","pandoc","pandoc-crossref","pandoc-filter"],"created_at":"2024-07-31T00:01:17.276Z","updated_at":"2026-01-31T14:07:22.662Z","avatar_url":"https://github.com/lierdakil.png","language":"Haskell","funding_links":[],"categories":["Haskell"],"sub_categories":[],"readme":"# pandoc-crossref filter ![Build status](https://github.com/lierdakil/pandoc-crossref/workflows/Haskell%20CI/badge.svg)\n\npandoc-crossref is a pandoc filter for numbering figures, equations,\ntables and cross-references to them.\n\nThe input file (like\n[demo.md](https://raw.githubusercontent.com/lierdakil/pandoc-crossref/master/docs/demo/demo.md)) can\nbe converted into\n[HTML](http://lierdakil.github.io/pandoc-crossref/demo/output.html),\n[LaTeX](http://lierdakil.github.io/pandoc-crossref/demo/output.latex),\n[PDF](http://lierdakil.github.io/pandoc-crossref/demo/output.pdf),\n[Markdown](http://lierdakil.github.io/pandoc-crossref/demo/output.md) or other\nformats.\n\nOptionally, you can use cleveref for LaTeX/PDF output, e.g. [cleveref\nPDF](http://lierdakil.github.io/pandoc-crossref/demo/output-cref.pdf),\n[cleveref\nLaTeX](http://lierdakil.github.io/pandoc-crossref/demo/output-cref.latex),\nand listings package, e.g. [listings\nPDF](http://lierdakil.github.io/pandoc-crossref/demo/output-listings.pdf),\n[listings\nLaTeX](http://lierdakil.github.io/pandoc-crossref/demo/output-listings.latex)\n\nYou can also enable per-chapter numbering (as with `--chapters` for\nlatex output). You need to specify `-M chapters` for non-LaTeX/PDF\noutput however. Examples:\n[HTML](http://lierdakil.github.io/pandoc-crossref/demo/output-chapters.html),\n[Markdown](http://lierdakil.github.io/pandoc-crossref/demo/output-chapters.md),\n[LaTeX](http://lierdakil.github.io/pandoc-crossref/demo/output-chapters.latex),\n[PDF](http://lierdakil.github.io/pandoc-crossref/demo/output-chapters.pdf).\n\nThis work is inspired by\n[pandoc-fignos](https://github.com/tomduck/pandoc-fignos) and\n[pandoc-eqnos](https://github.com/tomduck/pandoc-eqnos) by @tomduck.\n\nThis package tries to use LaTeX labels and references if output type is\nLaTeX. It also tries to supplement rudimentary LaTeX configuration that\nshould mimic metadata configuration by setting `header-includes`\nvariable.\n\n## Installation\n\nThe easiest option to get pandoc-crossref on Windows, macOS, or Linux, is to\ndownload pre-built executables available at the [releases\npage](https://github.com/lierdakil/pandoc-crossref/releases/latest).\nBear in mind that those are a product of automated build scripts, and as\nsuch, provided as-is, with zero guarantees. Feel free to open issues if those\ndon't work though, I'll try to do what I can.\n\n**WARNING:** When using pre-built executables, **make sure that your pandoc\nversion matches the version pandoc-crossref was built against, otherwise\nweird stuff will likely happen.** Feel free to open issues if there's a new\nversion of pandoc available, for which there are no pandoc-crossref builds.\n\nAlso, for those feeling adventurous, the automatic builds for the latest commits are available. Latest builds can be found on the [nightlies tag](https://github.com/lierdakil/pandoc-crossref/releases/tag/nightlies) (despite the name, those aren't actually built nightly, but on each push instead)\n\nIf you don't trust random binaries downloaded off the Internet (which is\ncompletely reasonable), you're welcome to build from source. You have two\npreferred options for that: building from Hackage with `cabal-install`, or from\nrepository with `stack` (you'll only need `stack` and maybe `git`). See below\nfor build instructions.\n\nIf you're completely new to Haskell, the latter, i.e. building from repo\nwith `stack`, is the easier option in most cases.\n\nThis repository is also a nix flake. You can use `nix` to get it installed.\n\nAlternatively, you can use a version provided by a third party. At the\ntime of writing, pandoc-crossref is provided on the following platforms\n(that I am aware of):\n\n-   Arch Linux\n-   NixOS or Nix package manager (via `nixpkgs.haskellPackages`\n    attribute)\n-   MacOS (via [Homebrew](https://brew.sh))\n-   FreeBSD official binary package [textproc/hs-pandoc-crossref](https://www.freshports.org/textproc/hs-pandoc-crossref/)\n-   Any Linux distribution (via [Linuxbrew](https://docs.brew.sh/Linuxbrew))\n-   Gentoo Linux (via gentoo-haskell overlay)\n-   Windows (via [scoop](https://scoop.sh/))\n\n### Building from Hackage with `cabal-install`\n\nYou'll need to get GHC and `cabal-install` installed first. By far the easiest way to get those is via [ghcup].\n\n[ghcup]: https://www.haskell.org/ghcup/\n\nDescribing using `ghcup` is out of scope for this small guide, but TL;DR is this:\n\n```\nghcup install ghc\nghcup install cabal\n```\n\nAfter you got `cabal-install` and `ghc`, run:\n\n``` bash\ncabal v2-update\ncabal v2-install --install-method=copy pandoc-cli pandoc-crossref\n```\n\nThis will get `pandoc-crossref` and `pandoc` executables copied to `$HOME/.cabal/bin` (by default, if not, check your cabal config file `installdir` setting -- find out where your config file is by running `cabal help user-config`), which you can then add to `PATH` or copy/move the symlinks where you want them.\n\nRefer to cabal documentation if you need to build a particular version (TL;DR: add `--constraint pandoc-crossref==\u003cversion\u003e` to the installation command)\n\n**Note**: if you're using cabal to build from a repo checkout, and not from Hackage as described above, you'll need to either **match the compiler version** specified in `ghcver` in `.github/workflows/haskell.yml`, or **remove `cabal.project.freeze`** from the root of the repository. Otherwise, cabal will complain about version mismatch of boot packages (like `base`, `ghc-boot-th`, etc)\n\n### Building from repo with `stack`\n\nFirst of all, get `stack` if you don't have it already: see the [official stack documentation][]. Note that `stack` can also be installed via [ghcup], and on Linux it is usually available in your package manager.\n\n[official stack documentation]: https://docs.haskellstack.org/en/stable/README/#how-to-install\n\nIf you have `git`, you can now clone the repository and build:\n\n``` bash\ngit clone https://github.com/lierdakil/pandoc-crossref.git\ncd pandoc-crossref\ngit checkout \u003ccommit/tag/branch\u003e\nstack install\n```\n\nIf you don't have `git`, just download the sources for your preferred commit/branch/tag via the GitHub interface, and run `stack install` in the directory that contains `stack.yaml` file.\n\nThis will install pandoc-crossef executable to `$HOME/.local/bin`. You might also want to separately run `stack install pandoc-cli` in the same directory (i.e. the root of the repository, the one containing `stack.yaml` file)\n\n### Installing as a nix flake\n\nTL;DR:\n\n```\nnix profile install github:lierdakil/pandoc-crossref\n```\n\nwill install the latest commit from the `master` branch. You can also specify a commit, branch or tag, e.g.:\n\n```\nnix profile install github:lierdakil/pandoc-crossref/71c8c8508c222bf4110794457fdf0391b05fb9a9\n```\n\nYou can also get the corresponding `pandoc` version installed via\n\n```\nnix profile install github:lierdakil/pandoc-crossref#pandoc\n```\n\nSince you will generally want both, there's an option to install both at the\nsame time, too:\n\n```\nnix profile install github:lierdakil/pandoc-crossref#pandoc-with-crossref\n```\n\nAside from added convenience, this guarantees pandoc and pandoc-crossref\nversions to be consistent across updates.\n\nFinally, you can start a nix shell with both `pandoc` and `pandoc-crossref`\nusing\n\n```\nnix develop github:lierdakil/pandoc-crossref\n```\n\n**Warning**: this uses [haskell.nix][] infrastructure for builds (because\nHaskell support in Nix is borked, and has been for a long time). This means that\nunless you use their substituters, you'll build multiple GHC versions from\nsource. To avoid that, add `https://cache.iog.io` to `substituters` in\n`nix.conf` and `hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=` to\n`trusted-public-keys`.\n\n[haskell.nix]: https://github.com/input-output-hk/haskell.nix\n\nYou can also use pandoc-crossref's binary cache by adding `https://pandoc-crossref.cachix.org` and `pandoc-crossref.cachix.org-1:LI9ABFTkGpPCTkUTzoopVSSpb1a26RSTJNMsqVbDtPM=` to `substituters` and `trusted-public-keys` respectively.\n\nThe flake includes both by default, so if you're a nix trusted user and accept\nthese configurations during flake evaluation those will be used automatically.\n\n### Notice Fedora users\n\n`cabal-install` package is not enough to build pandoc-crossref (see\n[\\#132](https://github.com/lierdakil/pandoc-crossref/issues/132)).\nTo get a sane Haskell build environment, you need to install the\n`haskell-platform` package (`dnf install haskell-platform`).\n\nWhile on topic, if you don't want to rebuild pandoc itself from source,\nmake sure you have `pandoc` and `ghc-pandoc-devel` dnf packages before\nattempting to build pandoc-crossref.\n\n## Usage\n\nUsage information is available at\n\u003chttps://lierdakil.github.io/pandoc-crossref/\u003e\n\n## Projects\nThe following projects use this filter:\n\n- [TechnicalMarkdown](https://github.com/gabyx/TechnicalMarkdown)\n\n# License\n\nThis program is free software; you can redistribute it and/or modify it\nunder the terms of the GNU General Public License as published by the\nFree Software Foundation; either version 2 of the License, or (at your\noption) any later version.\n\nSee\n[LICENSE](https://github.com/lierdakil/pandoc-crossref/blob/master/LICENSE)\nfor details.\n\n© 2016 Nikolay Yakimov et al\n\nContributors (per GPL, holders of copyright on their respective\ncontributions):\n\n\u003c!-- BEGIN CONTRIBUTORS LIST --\u003e\n-   Nikolay Yakimov\n-   Rui Chen\n-   gesh\n-   Raphael Das Gupta\n-   Masamichi Hosoda\n-   Felix Yan\n-   Wlad\n-   Wandmalfarbe\n-   Vekhir\n-   Silas Benson\n-   shutingrz\n-   Shaun Jackman\n-   scoavoux\n-   Salim B\n-   Matthew Salganik\n-   Jan-T. Brinkmann\n-   hseg\n-   Han Joosten\n-   Hadrien Mary\n-   Gleb Popov\n-   Gabriel Nützi\n-   David Arnold\n-   Chris Black\n-   Bart Mesuere\n-   Albert\n\n\u003c!-- END CONTRIBUTORS LIST --\u003e\n\nThis repository includes code from \u003chttps://github.com/roelvandijk/roman-numerals\u003e, covered by a different license. See\n[licenses/LICENSE.roman-numerals](https://github.com/lierdakil/pandoc-crossref/blob/master/licenses/LICENSE.roman-numerals)\nfor details.\n\n# How to bump pandoc version\n\n1. Change `PANDOC_VERSION` in `.github/workflows/haskell.yml` to the new Pandoc version.\n2. Relax version bounds in `package.yaml` if needed.\n3. Run `make update`. You need at least `nix`, `stack` and `cabal` (i.e. cabal-install) installed and in `PATH`.\n\n    If it doesn't do anything, consider nuking `cabal.project.freeze`, `flake.lock`, `stack.yaml` and `stack.yaml.lock` and trying again.\n4. Build and test.\n5. Fix broken tests.\n\n    Note that you can regenerate most golden tests with either\n    `make regen-test-fixtures` if using Nix, or just running `./mkcheck.sh` and\n    `./mkinttest.sh` with appropriate `pandoc` and `pandoc-crossref` binaries in\n    scope (so e.g. via `stack exec`).\n6. Repeat 4-5 until all tests pass.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flierdakil%2Fpandoc-crossref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flierdakil%2Fpandoc-crossref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flierdakil%2Fpandoc-crossref/lists"}