{"id":13714932,"url":"https://github.com/sirthias/pegdown","last_synced_at":"2025-05-14T15:06:24.084Z","repository":{"id":57739817,"uuid":"639740","full_name":"sirthias/pegdown","owner":"sirthias","description":"A pure-Java Markdown processor based on a parboiled PEG parser supporting a number of extensions","archived":false,"fork":false,"pushed_at":"2016-12-14T18:43:59.000Z","size":11716,"stargazers_count":1291,"open_issues_count":84,"forks_count":215,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-04-12T14:15:39.392Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://pegdown.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sirthias.png","metadata":{"files":{"readme":"README.markdown","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":"2010-04-30T11:44:16.000Z","updated_at":"2025-03-22T22:46:48.000Z","dependencies_parsed_at":"2022-09-01T10:50:24.800Z","dependency_job_id":null,"html_url":"https://github.com/sirthias/pegdown","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirthias%2Fpegdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirthias%2Fpegdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirthias%2Fpegdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sirthias%2Fpegdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sirthias","download_url":"https://codeload.github.com/sirthias/pegdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169044,"owners_count":22026207,"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-08-03T00:00:52.110Z","updated_at":"2025-05-14T15:06:24.036Z","avatar_url":"https://github.com/sirthias.png","language":"Java","readme":":\u003e\u003e\u003e DEPRECATION NOTE \u003c\u003c\u003c:\n==========================\n\nAlthough still one of the most popular Markdown parsing libraries for the JVM, *pegdown* has reached its end of life.\n\nThe project is essentially unmaintained with [tickets][issues] piling up and crucial bugs not being fixed.\u003cbr/\u003e\n*pegdown*'s parsing performance isn't great. In some cases of pathological input runtime can even become exponential,\nwhich means that the parser either appears to \"hang\" completely or abort processing after a time-out.\n\nTherefore *pegdown* is not recommended anymore for use in new projects requiring a markdown parser.\u003cbr/\u003e\nInstead I suggest you turn to [@vsch]'s [flexmark-java], which appears to be an excellent replacement for these reasons:\n\n* Modern parser architecture (based on [commonmark-java]), designed from the ground up as a *pegdown* replacement and\n  supporting all its features and extensions\n* 30x better average parsing performance without pathological input cases\n* Configuration options for a multitude of markdown dialects ([CommonMark], pegdown, [MultiMarkdown], [kramdown] and [Markdown.pl])\n* Actively maintained and used as the basis of an [IntelliJ plugin] with almost 2M downloads per year\n* The author ([@vsch]) has actively contributed to *pegdown* maintenance in the last two years and is intimately familiar with *pegdown*'s internals and quirks.\n\nIn case you need support with migrating from *pegdown* to [flexmark-java], [@vsch] welcomes inquiries in [here][issues] or [here][flexmark-java issues].\n\n[issues]: https://github.com/sirthias/pegdown/issues\n[@vsch]: https://github.com/vsch\n[flexmark-java]: https://github.com/vsch/flexmark-java\n[commonmark-java]: https://github.com/atlassian/commonmark-java\n[CommonMark]: http://spec.commonmark.org/0.27/\n[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/\n[kramdown]: https://kramdown.gettalong.org/\n[Markdown.pl]: http://search.cpan.org/~sekimura/Text-Markdown-Discount-0.11/xt/MarkdownXS.pl\n[IntelliJ plugin]: https://vladsch.com/product/markdown-navigator\n[flexmark-java issues]: https://github.com/vsch/flexmark-java/issues\n\n\n---\n\n\nIntroduction\n------------\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.pegdown/pegdown/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.pegdown/pegdown)\n[![Javadoc](https://javadoc-emblem.rhcloud.com/doc/org.pegdown/pegdown/badge.svg)](http://www.javadoc.io/doc/org.pegdown/pegdown)\n\n_pegdown_ is a pure Java library for clean and lightweight [Markdown] processing based on a [parboiled] PEG parser.\n\n_pegdown_ is nearly 100% compatible with the original Markdown specification and fully passes the original Markdown test suite.\nOn top of the standard Markdown feature set _pegdown_ implements a number of extensions similar to what other popular\nMarkdown processors offer. You can also extend _pegdown_ by your own plugins!\nCurrently _pegdown_ supports the following extensions over standard Markdown:\n\n* SMARTS: Beautifies apostrophes, ellipses (\"...\" and \". . .\") and dashes (\"--\" and \"---\")\n* QUOTES: Beautifies single quotes, double quotes and double angle quotes (\u0026laquo; and \u0026raquo;)\n* SMARTYPANTS: Convenience extension enabling both, SMARTS and QUOTES, at once.\n* ABBREVIATIONS: Abbreviations in the way of [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/#abbr).\n* ANCHORLINKS: Generate anchor links for headers by taking the first range of alphanumerics and spaces.\n* HARDWRAPS: Alternative handling of newlines, see [Github-flavoured-Markdown]\n* AUTOLINKS: Plain (undelimited) autolinks the way [Github-flavoured-Markdown] implements them.\n* TABLES: Tables similar to [MultiMarkdown](http://fletcherpenney.net/multimarkdown/) (which is in turn like the [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/#table) tables, but with colspan support).\n* DEFINITION LISTS: Definition lists in the way of [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/#def-list).\n* FENCED CODE BLOCKS: Fenced Code Blocks in the way of [PHP Markdown Extra](http://michelf.com/projects/php-markdown/extra/#fenced-code-blocks) or [Github-flavoured-Markdown].\n* HTML BLOCK SUPPRESSION: Suppresses the output of HTML blocks.\n* INLINE HTML SUPPRESSION: Suppresses the output of inline HTML elements.\n* WIKILINKS: Support `[[Wiki-style links]]` with a customizable URL rendering logic.\n* STRIKETHROUGH: Support ~~strikethroughs~~ as supported in Pandoc and Github.\n* ATXHEADERSPACE: Require a space between the `#` and the header title text, as per [Github-flavoured-Markdown]. Frees up `#` without a space to be just plain text.\n* FORCELISTITEMPARA: Wrap a list item or definition term in `\u003cp\u003e` tags if it contains more than a simple paragraph.\n* RELAXEDHRULES: allow horizontal rules without a blank line following them.\n* TASKLISTITEMS: parses bullet lists of the form `* [ ]` and `* [x]` to create GitHub like task list items:\n    * [ ] open task item\n    * [x] closed or completed task item.\n    * [X] also closed or completed task item.\n* EXTANCHORLINKS: Generate anchor links for headers using complete contents of the header.\n    * Spaces and non-alphanumerics replaced by `-`, multiple dashes trimmed to one.\n    * Anchor link is added as first element inside the header with empty content: `\u003ch1\u003e\u003ca name=\"header\"\u003e\u003c/a\u003eheader\u003c/h1\u003e`\n                        \nNote: _pegdown_ differs from the original Markdown in that it ignores in-word emphasis as in\n\n    \u003e my_cool_file.txt\n    \u003e 2*3*4=5\n\nCurrently this \"extension\" cannot be switched off.\n\n\nInstallation\n------------\n\nYou have two options:\n\n* Download the JAR for the latest version from [here](http://repo1.maven.org/maven2/org/pegdown/pegdown/).\n  _pegdown_ 1.6.0 has only one dependency: [parboiled for Java][parboiled], version 1.1.7.\n   \n* The pegdown artifact is also available from maven central with group id **org.pegdown** and artifact-id **pegdown**.\n\n\nUsage\n-----\n\nUsing _pegdown_ is very simple: Just create a new instance of a [PegDownProcessor] and call one of its\n`markdownToHtml` methods to convert the given Markdown source to an HTML string. If you'd like to customize the\nrendering of HTML links (Auto-Links, Explicit-Links, Mail-Links, Reference-Links and/or Wiki-Links), e.g. for adding\n`rel=\"nofollow\"` attributes based on some logic you can supply your own instance of a [LinkRenderer] with the call\nto `markdownToHtml`.\n\nYou can also use pegdown only for the actual parsing of the Markdown source and do the serialization to the\ntarget format (e.g. XML) yourself. To do this just call the `parseMarkdown` method of the [PegDownProcessor] to obtain\nthe root node of the Abstract Syntax Tree for the document.\nWith a custom [Visitor] implementation you can do whatever serialization you want. As an example you might want to\ntake a look at the [sources of the ToHtmlSerializer][ToHtmlSerializer].\n\nNote that the first time you create a [PegDownProcessor] it can take up to a few hundred milliseconds to prepare the\nunderlying parboiled parser instance. However, once the first processor has been built all further instantiations will\nbe fast. Also, you can reuse an existing [PegDownProcessor] instance as often as you want, as long as you prevent\nconcurrent accesses, since neither the [PegDownProcessor] nor the underlying parser is thread-safe.\n\nSee \u003chttp://sirthias.github.com/pegdown/api\u003e for the pegdown API documentation.\n\n\nPlugins\n-------\n\nSince parsing and serialisation are two different things there are two different plugin mechanisms, one for the parser,\nand one for the [ToHtmlSerializer]. Most plugins would probably implement both, but it is possible that a plugin might\njust implement the parser plugin interface.\n\nFor the parser there are two plugin points, one for inline plugins (inside a paragraph) and one for block plugins. These\nare provided to the parser using the [PegDownPlugins] class. For convenience of use this comes with its own builder.\nYou can either pass individual rules to this builder (which is what you probably would do if you were using Scala\nrules), but you can also pass it a parboiled Java parser class which implements either [InlinePluginParser] or\n[BlockPluginParser] or both. [PegDownPlugins] will enhance this parser for you, so as a user of a plugin you just need\nto pass the class to it (and the arguments for that classes constructor, if any). To implement the plugin, you would\nwrite a normal parboiled parser, and implement the appropriate parser plugin interface. You can extend the pegdown\nparser, this is useful if you want to reuse any of its rules.\n\nFor the serializer there is [ToHtmlSerializerPlugin] interface. It is called when a node that the [ToHtmlSerializer]\ndoesn't know how to process is encountered (i.e. one produced by a parser plugin). Its `accept` method is passed the\nnode, the visitor (so if the node contains child nodes they can be rendered using the parent) and the printer for the\nplugin to print to. The `accept` method returns true if it knew how to handle the node or false if otherwise and\nthe [ToHtmlSerializer] loops through each plugin breaking when it reaches one that returns true and if it finds none\nthrows an exception like it used to.\n\nAs an very simple example you might want to take a look at the [sources of the PluginParser test class][PluginParser].\n\n\nParsing Timeouts\n----------------\n\nSince Markdown has no official grammar and contains a number of ambiguities the parsing of Markdown source, especially\nwith enabled language extensions, can be \"hard\" and result, in certain corner cases, in exponential parsing time.\nIn order to provide a somewhat predictable behavior *pegdown* therefore supports the specification of a parsing timeout,\nwhich you can supply to the [PegDownProcessor] constructor.\n\nIf the parser happens to run longer than the specified timeout period it terminates itself with an exception, which\ncauses the `markdownToHtml` method to return `null`. Your application should then deal with this case accordingly and,\nfor example, inform the user.\n\nThe default timeout, if not explicitly specified, is 2 seconds.\n\n\nIDE Support\n-----------\n\nThe excellent [idea-markdown plugin] for IntelliJ IDEA, RubyMine, PhpStorm, WebStorm, PyCharm and appCode uses _pegdown_\nas its underlying parsing engine. The plugin gives you proper syntax-highlighting for markdown source and shows you\nexactly, how _pegdown_ will parse your texts.\n\n\nCredits\n-------\n\nA large part of the underlying PEG grammar was developed by John MacFarlane and made available with his\ntool [peg-markdown](http://github.com/jgm/peg-markdown).   \n\n\nLicense\n-------\n\n_pegdown_ is licensed under [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0).\n\n\nPatch Policy\n------------\n\nFeedback and contributions to the project, no matter what kind, are always very welcome.\nHowever, patches can only be accepted from their original author.\nAlong with any patches, please state that the patch is your original work and that you license the work to the pegdown\nproject under the project’s open source license.\n  \n   [Markdown]: http://daringfireball.net/projects/markdown/ \"Main Markdown site\"\n   [parboiled]: http://www.parboiled.org\n   [Github-flavoured-Markdown]: http://github.github.com/github-flavored-markdown/\n   [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/users_guide/multimarkdown_syntax_guide/\n   [PegDownProcessor]: http://www.decodified.com/pegdown/api/org/pegdown/PegDownProcessor.html\n   [LinkRenderer]: http://www.decodified.com/pegdown/api/org/pegdown/LinkRenderer.html\n   [Visitor]: http://www.decodified.com/pegdown/api/org/pegdown/ast/Visitor.html\n   [ToHtmlSerializer]: https://github.com/sirthias/pegdown/blob/master/src/main/java/org/pegdown/ToHtmlSerializer.java\n   [idea-markdown plugin]: https://github.com/nicoulaj/idea-markdown\n   [SBT]: http://www.scala-sbt.org/\n   [Node]: http://www.decodified.com/pegdown/api/org/pegdown/ast/Node.html\n   [PegDownPlugins]: http://github.com/sirthias/pegdown/blob/master/src/main/java/org/pegdown/plugins/PegDownPlugins.java\n   [InlinePluginParser]: http://github.com/sirthias/pegdown/blob/master/src/main/java/org/pegdown/plugins/InlinePluginParser.java\n   [BlockPluginParser]: http://github.com/sirthias/pegdown/blob/master/src/main/java/org/pegdown/plugins/BlockPluginParser.java\n   [ToHtmlSerializerPlugin]: http://github.com/sirthias/pegdown/blob/master/src/main/java/org/pegdown/plugins/ToHtmlSerializerPlugin.java\n   [PluginParser]: http://github.com/sirthias/pegdown/blob/master/src/test/java/org/pegdown/PluginParser.java\n","funding_links":[],"categories":["Java","Libraries","III. Network and Integration"],"sub_categories":["Java","7. Web Crawling and HTML parsering"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsirthias%2Fpegdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsirthias%2Fpegdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsirthias%2Fpegdown/lists"}