{"id":13687363,"url":"https://github.com/gmarpons/asciidoc-hs","last_synced_at":"2026-01-21T08:54:38.865Z","repository":{"id":45273146,"uuid":"271343726","full_name":"gmarpons/asciidoc-hs","owner":"gmarpons","description":"AsciiDoc parser that can be used as a Pandoc front-end, written in Haskell","archived":false,"fork":false,"pushed_at":"2021-12-25T21:53:22.000Z","size":426,"stargazers_count":47,"open_issues_count":20,"forks_count":4,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-08-03T15:06:28.417Z","etag":null,"topics":["asciidoc","docs-as-code","haskell","pandoc"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmarpons.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","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":"2020-06-10T17:37:14.000Z","updated_at":"2024-05-22T13:39:04.000Z","dependencies_parsed_at":"2022-09-19T09:50:22.095Z","dependency_job_id":null,"html_url":"https://github.com/gmarpons/asciidoc-hs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmarpons%2Fasciidoc-hs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmarpons%2Fasciidoc-hs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmarpons%2Fasciidoc-hs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmarpons%2Fasciidoc-hs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmarpons","download_url":"https://codeload.github.com/gmarpons/asciidoc-hs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224257599,"owners_count":17281746,"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":["asciidoc","docs-as-code","haskell","pandoc"],"created_at":"2024-08-02T15:00:53.455Z","updated_at":"2026-01-21T08:54:38.820Z","avatar_url":"https://github.com/gmarpons.png","language":"Haskell","funding_links":[],"categories":["Haskell"],"sub_categories":[],"readme":"= Asciidoc-hs\n:toc: macro\nifndef::env-github[]\n:icons: font\n:outfilesuffix: .adoc\n:caution-caption: :fire:\n:important-caption: :exclamation:\n:note-caption: :paperclip:\n:tip-caption: :bulb:\n:warning-caption: :warning:\nendif::[]\n// Variables:\n:release-version:\n// URLs:\n:url-repo: https://github.com/gmarpons/asciidoc-hs\n\nWARNING: This project is in its early stages.\nDon't expect to be able to use it in anything relevant, yet.\n\n`asciidoc-hs` is a parser for the lightweight markup language https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc] that can be used as a https://pandoc.org/[Pandoc] front-end.\nIt draws on https://github.com/jgm/commonmark-hs[`commonmark-hs`] and is written in pure Haskell.\n\nimage:https://github.com/gmarpons/asciidoc-hs/workflows/CI/badge.svg[Build Status (GitHub Actions),link={url-repo}/actions]\n\ntoc::[]\n\n== Mission\n\nThe main goal of this project is to become a reasonably complete implementation of the AsciiDoc language and to allow Pandoc to read AsciiDoc documents.\n\nWe want to read AsciiDoc as it's used today (mainly in its https://docs.asciidoctor.org/asciidoctor/latest/[Asciidoctor] variant), and also support the https://www.eclipse.org/org/workinggroups/asciidoc-charter.php[AsciiDoc Standard] when it arrives.\nWe're following the standardization process closely and we'll try to contribute to it if we see the opportunity.\n\nThere have been former attempts at a Pandoc Reader for AsciiDoc, but they have been abandoned.\nIf you want to feed Pandoc with an AsciiDoc source, your best option at the moment is probably to first convert to Docbook using Asciidoctor.\n\nSecondary goals of the project are (but don't expect any roadmap or timeline at the moment):\n\n* Be used as infrastructure for building advanced editor and IDE features (e.g., linters and live previewers).\nThis means to be able to track precise source mapping information, among others.\n\n* Be scriptable in a similar way to Pandoc, but using and AST/DOM that is specific to AsciiDoc and fully supports its semantic richness.\n\n* Enable source-to-source transformations, including exact-print for those parts not explicitly modified by the scripts (a.k.a. lossless transformation).\n\n* End up being distributed together with Pandoc, as a regular Pandoc Reader.\n\n== Features\n\nThe supported features can be found in our https://github.com/gmarpons/asciidoc-hs/wiki/AsciiDoc-Compatibility-Matrix[compatibility matrix], currently based on Asciidoctor's feature list.\n\n== Install\n\nYou'll need to build from source for the time being.\nWe expect to upload the package to Hackage soon.\n\nIf you don't have Haskell installed in your system, try install GHC and Cabal with https://www.haskell.org/ghcup/[`ghcup`], and follow instructions for Cabal below.\n\n`asciidoc-hs` has been tested with GHC 8.8 and 8.10, and Cabal 3.4.\n\n=== Using Cabal\n\nFirst, clone the repository:\n\n[subs=attributes]\n  $ git clone {url-repo}.git\n  $ cd asciidoc-hs\n\nThen, build using `cabal`:\n\n  $ cabal build\n\nYou can optionally copy the resulting executable under a location of your choice (that should be under the `PATH` environment variable):\n\n  $ cp \"$(cabal exec --verbose=0 --offline sh -- -c 'command -v asciidoc-hs')\" ~/.local/bin/asciidoc-hs\n\n=== Using Stack\n\nFirst, clone the repository:\n\n[subs=attributes]\n  $ git clone {url-repo}.git\n  $ cd asciidoc-hs\n\nThen, build using `stack`:\n\n  $ stack build\n\nYou can optionally copy the resulting executable under a location of your choice (that should be under the `PATH` environment variable):\n\n  $ cp \"$(stack path --local-install-root)/bin/asciidoc-hs\" ~/.local/bin/asciidoc-hs\n\n== Use\n\nIn the https://github.com/gmarpons/asciidoc-hs/tree/main/examples[examples] directory of this repository you can find some example AsciiDoc files and its various conversions.\n\nThe commands used to get the converted files are:\n\n:filename: ⟨FILENAME⟩\n\n* Convert to HTML using Asciidoctor:\n+\n[subs=attributes]\n  $ asciidoctor -a \"sectids!\" -a \"showtitle\" -a \"linkcss\" -a \"stylesheet=https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@2.0/data/stylesheets/asciidoctor-default.css\" -a \"webfonts!\" {filename}.adoc -o - \u003e {filename}-asciidoctor.html\n\n* Convert to HTML using `asciidoc-hs` + Pandoc:\n+\n[subs=attributes]\n  $ cat {filename}.adoc | asciidoc-hs | pandoc -f json -t html5 --standalone --css=\"https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@2.0/data/stylesheets/asciidoctor-default.css\" --css=\"./asciidoc-hs.css\" \u003e {filename}-pandoc.html\n\n* Convert to ODT using `asciidoc-hs` + Pandoc:\n+\n[subs=attributes]\n  $ cat {filename}.adoc | asciidoc-hs | pandoc -f json -t odt \u003e {filename}-pandoc.odt\n\n* Convert to Markdown using `asciidoc-hs` + Pandoc:\n+\n[subs=attributes]\n  $ cat {filename}.adoc | asciidoc-hs | pandoc -f json -t markdown_strict \u003e {filename}-pandoc.md\n\nFile https://github.com/gmarpons/asciidoc-hs/blob/main/examples/asciidoctor-article-template.adoc[`asciidoctor-article-template.adoc`] presents a variety of AsciiDoc features.\nThose not yet supported by `asciidoc-hs` are commented out.\n\n== Contribute\n\nContributions are Welcome!\n\nFor any of:\n\n* reporting a bug,\n* filling a feature request,\n* opening a PR,\n\nwe'll try to stick to the workflow and guidelines set in https://github.com/kowainik/.github/blob/main/CONTRIBUTING.md[Kowainik contributing guidelines], with the difference that we use https://hackage.haskell.org/package/ormolu[`ormolu`] instead of http://hackage.haskell.org/package/stylish-haskell[`stylish-haskell`].\n\n=== Implement a new AsciiDoc feature\n\nAsciiDoc is an extensive language.\nThere are plenty of features still to be implemented, with varying degrees of difficulty.\n\nThe recommended workflow is the following:\n\n. Check the https://github.com/gmarpons/asciidoc-hs/wiki/AsciiDoc-Compatibility-Matrix[compatibility matrix] to look for unsupported features.\n. Fill an issue with the proposed feature if you cannot find it in the https://github.com/gmarpons/asciidoc-hs/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement[issue tracker], yet.\n. Go inspect files https://github.com/gmarpons/asciidoc-hs/blob/main/src/Text/AsciiDoc/Inlines.hs[Inlines.hs] or https://github.com/gmarpons/asciidoc-hs/blob/main/src/Text/AsciiDoc/Blocks.hs[Blocks.hs] and see:\n** If the current AST data types (mainly `Inline` and `Block`) support the intended feature, or need to be modified.\n** Look for a similar and already implemented feature, and see how the corresponding parser functions are written.\n. Discuss a possible implementation in the issue tracker.\n. Modify the aforementioned files.\n. Add new https://github.com/gmarpons/asciidoc-hs/tree/main/test/Tests[test cases] for inlines or blocks.\n. Add the necessary new cases to functions `convertInline` or `convertBlock` in https://github.com/gmarpons/asciidoc-hs/blob/main/src/Text/AsciiDoc/Pandoc.hs[Pandoc.hs].\n\nYou don't need to wait to complete the steps above before opening a PR.\nIn fact, it's better if your code can be reviewed from the beginning.\n\n== Acknowledgements\n\nThis work has been supported by a https://www.tweag.io/blog/2020-02-14-os-fellowship/[Tweag Open Source Fellowship].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmarpons%2Fasciidoc-hs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmarpons%2Fasciidoc-hs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmarpons%2Fasciidoc-hs/lists"}