https://github.com/JohannesKaufmann/html-to-markdown Skip to content Navigation Menu Toggle navigation Sign in * Product + GitHub Copilot Write better code with AI + Security Find and fix vulnerabilities + Actions Automate any workflow + Codespaces Instant dev environments + Issues Plan and track work + Code Review Manage code changes + Discussions Collaborate outside of code + Code Search Find more, search less Explore + All features + Documentation + GitHub Skills + Blog * Solutions By company size + Enterprises + Small and medium teams + Startups By use case + DevSecOps + DevOps + CI/CD + View all use cases By industry + Healthcare + Financial services + Manufacturing + Government + View all industries View all solutions * Resources Topics + AI + DevOps + Security + Software Development + View all Explore + Learning Pathways + White papers, Ebooks, Webinars + Customer Stories + Partners * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles Repositories + Topics + Trending + Collections * Enterprise + Enterprise platform AI-powered developer platform Available add-ons + Advanced Security Enterprise-grade security features + GitHub Copilot Enterprise-grade AI features + Premium Support Enterprise-grade 24/7 support * Pricing Search or jump to... Search code, repositories, users, issues, pull requests... Search [ ] Clear Search syntax tips Provide feedback We read every piece of feedback, and take your input very seriously. [ ] [ ] Include my email address so I can be contacted Cancel Submit feedback Saved searches Use saved searches to filter your results more quickly Name [ ] Query [ ] To see all available qualifiers, see our documentation. Cancel Create saved search Sign in Sign up Reseting focus You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert {{ message }} JohannesKaufmann / html-to-markdown Public * Notifications You must be signed in to change notification settings * Fork 92 * Star 1.3k [?][?] Convert HTML to Markdown. Even works with entire websites and can be extended through rules. html-to-markdown.com License MIT license 1.3k stars 92 forks Branches Tags Activity Star Notifications You must be signed in to change notification settings * Code * Issues 8 * Pull requests 0 * Actions * Security * Insights Additional navigation options * Code * Issues * Pull requests * Actions * Security * Insights JohannesKaufmann/html-to-markdown main BranchesTags [ ] Go to file Code Folders and files Name Name Last commit Last commit message date Latest commit History 131 Commits .github .github cli cli collapse collapse converter converter examples examples internal internal marker marker plugin plugin .DS_Store .DS_Store .gitignore .gitignore .goreleaser.yaml .goreleaser.yaml ESCAPING.md ESCAPING.md LICENSE LICENSE README.md README.md SECURITY.md SECURITY.md WRITING_PLUGINS.md WRITING_PLUGINS.md convert.go convert.go convert_test.go convert_test.go go.mod go.mod go.sum go.sum View all files Repository files navigation * README * MIT license * Security html-to-markdown A robust html-to-markdown converter that transforms HTML (even entire websites) into clean, readable Markdown. It supports complex formatting, customizable options, and plugins for full control over the conversion process. Use the fully extendable Golang library or a quick CLI command. Alternatively, try the Online Demo or REST API to see it in action! Here are some cool features: * Bold & Italic: Supports bold and italic--even within single words. [point_bold] * List: Handles ordered and unordered lists with full nesting support. [point_list] * Blockquote: Blockquotes can include other elements, with seamless support for nested quotes. [point_bloc] * Inline Code & Code Block: Correctly handles backticks and multi-line code blocks, preserving code structure. [point_code] * Link & Image: Properly formats multi-line links, adding escapes for blank lines where needed. [point_link] * Smart Escaping: Escapes special characters only when necessary, to avoid accidental Markdown rendering. [?] ESCAPING.md [point_esca] * Remove/Keep HTML: Choose to strip or retain specific HTML tags for ultimate control over output. [point_wrap] * Plugins: Easily extend with plugins. Or create custom ones to enhance functionality. [point_stri] --------------------------------------------------------------------- --------------------------------------------------------------------- Golang Library Installation go get -u github.com/JohannesKaufmann/html-to-markdown/v2 Or if you want a specific commit add the suffix /v2@commithash Note This is the documentation for the v2 library. For the old version switch to the "v1" branch. Usage Go V2 Reference package main import ( "fmt" "log" htmltomarkdown "github.com/JohannesKaufmann/html-to-markdown/v2" ) func main() { input := `Bold Text` markdown, err := htmltomarkdown.ConvertString(input) if err != nil { log.Fatal(err) } fmt.Println(markdown) // Output: **Bold Text** } * Example code, basics The function htmltomarkdown.ConvertString() is a small wrapper around converter.NewConverter() and the base and commonmark plugins. If you want more control, use the following: package main import ( "fmt" "log" "github.com/JohannesKaufmann/html-to-markdown/v2/converter" "github.com/JohannesKaufmann/html-to-markdown/v2/plugin/base" "github.com/JohannesKaufmann/html-to-markdown/v2/plugin/commonmark" ) func main() { input := `Bold Text` conv := converter.NewConverter( converter.WithPlugins( base.NewBasePlugin(), commonmark.NewCommonmarkPlugin( commonmark.WithStrongDelimiter("__"), // ...additional configurations for the plugin ), ), ) markdown, err := conv.ConvertString(input) if err != nil { log.Fatal(err) } fmt.Println(markdown) // Output: __Bold Text__ } * Example code, options Note If you use NewConverter directly make sure to also register the commonmark and base plugin. Plugins Published Plugins These are the plugins located in the plugin folder: Name Description Base Implements basic shared functionality (e.g. removing nodes) Commonmark Implements Markdown according to the Commonmark Spec GitHubFlavored planned TaskListItems planned Strikethrough Converts , , and to the ~~ syntax. Table planned VimeoEmbed planned YoutubeEmbed planned ConfluenceCodeBlock planned ConfluenceAttachments planned Note Not all the plugins from v1 are already ported to v2. These will soon be implemented... These are the plugins in other repositories: Name Description [Plugin Name](Your Link) A short description Writing Plugins You want to write custom logic? 1. Write your logic and register it. [autocomple] + Example code, register 2. Optional: Package your logic into a plugin and publish it. + [?] WRITING_PLUGINS.md --------------------------------------------------------------------- --------------------------------------------------------------------- CLI - Using it on the command line Using the Golang library provides the most customization, while the CLI is the simplest way to get started. Installation Homebrew Tap brew install JohannesKaufmann/tap/html2markdown Manually Download the pre-compiled binaries from the releases page and copy them to the desired location. Version html2markdown --version Note Make sure that --version prints 2.X.X as there is a different CLI for V2 of the converter. Usage $ echo "important" | html2markdown **important** $ curl --no-progress-meter http://example.com | html2markdown # Example Domain This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission. [More information...](https://www.iana.org/domains/example) (The cli does not support every option yet. Over time more customization will be added) --------------------------------------------------------------------- --------------------------------------------------------------------- FAQ Extending with Plugins * Need your own logic? Write your own code and then register it. + Don't like the defaults that the library uses? You can use PriorityEarly to run you logic earlier than others. + Example code, register * If you believe that you logic could also benefit others, you can package it up into a plugin. + [?] WRITING_PLUGINS.md Bugs You found a bug? Open an issue with the HTML snippet that does not produce the expected results. Please, please, plase submit the HTML snippet that caused the problem. Otherwise it is very difficult to reproduce and fix... Security This library produces markdown that is readable and can be changed by humans. Once you convert this markdown back to HTML (e.g. using goldmark or blackfriday) you need to be careful of malicious content. This library does NOT sanitize untrusted content. Use an HTML sanitizer such as bluemonday before displaying the HTML in the browser. [?] SECURITY.md if you find a security vulnerability Goroutines You can use the Converter from (multiple) goroutines. Internally a mutex is used & there is a test to verify that behaviour. Escaping & Backslash Some characters have a special meaning in markdown (e.g. "*" for emphasis). The backslash \ character is used to "escape" those characters. That is perfectly safe and won't be displayed in the final render. [?] ESCAPING.md Contributing You want to contribute? Thats great to hear! There are many ways to help: Helping to answer questions, triaging issues, writing documentation, writing code, ... If you want to make a code change: Please first discuss the change you wish to make, by opening an issue. I'm also happy to guide you to where a change is most likely needed. There are also extensive tests (see below) so you can freely experiment Note: The outside API should not change because of backwards compatibility... Testing You don't have to be afraid of breaking the converter, since there are many "Golden File" tests: Add your problematic HTML snippet to one of the .in.html files in the testdata folders. Then run go test -update and have a look at which .out.md files changed in GIT. You can now change the internal logic and inspect what impact your change has by running go test -update again. Note: Before submitting your change as a PR, make sure that you run those tests and check the files into GIT... License Unless otherwise specified, the project is licensed under the terms of the MIT license. [?] LICENSE About [?][?] Convert HTML to Markdown. Even works with entire websites and can be extended through rules. html-to-markdown.com Topics go html markdown cli golang converter html-to-markdown Resources Readme License MIT license Security policy Security policy Activity Stars 1.3k stars Watchers 12 watching Forks 92 forks Report repository Releases 21 v2.1.0 Latest Nov 6, 2024 + 20 releases Packages 0 No packages published Used by 680 * @jonasbg * @MarkWalters-dev * @LaVidaHermosa * @bramble555 * @akymaky * @HeyManLean * @zmj6788 * @sammcj + 672 Contributors 10 * * * * * * * * * * Languages * Go 100.0% Footer (c) 2024 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact * Manage cookies * Do not share my personal information You can't perform that action at this time.