From fbd899d43983e7e4a8aa49f95d15ccf6c906a552 Mon Sep 17 00:00:00 2001 From: Tong Sun Date: Tue, 2 May 2023 23:43:14 -0400 Subject: - [#] update README --- README.md | 154 +++++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 108 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 6d8cf7a..de91632 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,30 @@ +# html2md + +[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-) + [![MIT License](http://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![GoDoc](https://godoc.org/github.com/suntong/html2md?status.svg)](http://godoc.org/github.com/suntong/html2md) [![Go Report Card](https://goreportcard.com/badge/github.com/suntong/html2md)](https://goreportcard.com/report/github.com/suntong/html2md) -[![travis Status](https://travis-ci.org/suntong/html2md.svg?branch=master)](https://travis-ci.org/suntong/html2md) -[![PoweredBy WireFrame](https://github.com/go-easygen/wireframe/blob/master/PoweredBy-WireFrame-R.svg)](http://godoc.org/github.com/go-easygen/wireframe) +[![Build Status](https://github.com/suntong/html2md/actions/workflows/go-release-build.yml/badge.svg?branch=master)](https://github.com/suntong/html2md/actions/workflows/go-release-build.yml) +[![PoweredBy WireFrame](https://github.com/go-easygen/wireframe/blob/master/PoweredBy-WireFrame-B.svg)](http://godoc.org/github.com/go-easygen/wireframe) -# TOC + + +## TOC - [html2md - HTML to Markdown converter](#html2md---html-to-markdown-converter) - [Usage](#usage) - [$ html2md](#-html2md) -- [Examples](#examples) - - [Simplest form](#simplest-form) - - [Using goquery](#using-goquery) + - [Examples](#examples) + - [Simplest form](#simplest-form) + - [Using goquery](#using-goquery) - [The options and plugins](#the-options-and-plugins) - - [Testing the new table plugins](#testing-the-new-table-plugins) -- [Download/Install](#downloadinstall) - - [Download binaries](#download-binaries) - - [Install Source](#install-source) -- [Credits & Authors](#credits-&-authors) + - [Testing the new table plugins](#testing-the-new-table-plugins) - [Credits](#credits) - - [Similar Projects](#similar-projects) - - [Author(s) & Contributor(s)](#author(s)-&-contributor(s)) + - [Credits](#credits-1) + - [Similar Projects](#similar-projects) -# html2md - HTML to Markdown converter +## html2md - HTML to Markdown converter The `html2md` makes use of `github.com/JohannesKaufmann/html-to-markdown` to convert HTML into Markdown, which is using an [HTML Parser](https://github.com/PuerkitoBio/goquery) to avoid the use of `regexp` as much as possible, which can prevent some [weird cases](https://stackoverflow.com/a/1732454) and allows it to be used for cases where the input is totally unknown. @@ -30,13 +32,13 @@ to convert HTML into Markdown, which is using an [HTML Parser](https://github.co ![gopher stading on top of a machine that converts a box of html to blocks of markdown](https://github.com/JohannesKaufmann/html-to-markdown/raw/master/logo.png) -# Usage +## Usage ### $ html2md ```sh HTML to Markdown -Version 0.2.01 built on 2020-08-08 -Copyright (C) 2020, Tong Sun +Version 1.0.0 built on 2023-05-02 +Copyright (C) 2020-2023, Tong Sun HTML to Markdown converter on command line @@ -60,6 +62,7 @@ Options: --opt-strong-delimiter Option StrongDelimiter --opt-link-style Option LinkStyle --opt-link-reference-style Option LinkReferenceStyle + --opt-escape-mode Option EscapeMode -A, --plugin-conf-attachment Plugin ConfluenceAttachments -C, --plugin-conf-code Plugin ConfluenceCodeBlock @@ -73,9 +76,9 @@ Options: -Y, --plugin-youtube Plugin YoutubeEmbed ``` -# Examples +### Examples -## Simplest form +#### Simplest form ```md $ html2md -i https://github.com/suntong/html2md | head -3 @@ -84,7 +87,7 @@ $ html2md -i https://github.com/suntong/html2md | head -3 [Homepage](https://github.com/) ``` -## Using goquery +#### Using goquery The most useful feature is to use and pass a [goquery](https://github.com/PuerkitoBio/goquery) selection to filter for the content you want. @@ -93,7 +96,7 @@ $ html2md -i https://github.com/JohannesKaufmann/html-to-markdown -s "div.Border ``` -## The options and plugins +### The options and plugins Works as expected: @@ -113,7 +116,7 @@ $ echo 'Only blue ones left' | html2md -i --plugin-strikethro Only ~blue ones~ ~left~ ``` -## Testing the new table plugins +#### Testing the new table plugins ```sh $ cat $GOPATH/src/github.com/JohannesKaufmann/html-to-markdown/testdata/TestPlugins/table/input.html | html2md -i -T | head -6 @@ -146,47 +149,106 @@ $ cat $GOPATH/src/github.com/JohannesKaufmann/html-to-markdown/testdata/TestPlug + ``` -# Download/Install - +## Credits -## Download binaries -- The latest binary executables are available right under the github release page -https://github.com/suntong/html2md/releases -as the result of the Continuous-Integration process. -- I.e., they are built during every git tagged push, automatically by [GitHub Actions](https://github.com/features/actions), right from the source code, truely WYSIWYG. -- The `.deb`, `.rpm` and `.apk` packages are readily available, as well as the executables for other Linux and Windows as well. -- Pick & choose the binary executable that suits your OS and its architecture. E.g., for Linux, it would most probably be the `html2md_ver_linux_amd64.tar.gz` file. -- Unzip it and put the executable somewhere in the PATH, after downloading it. +### Credits +- [Johannes Kaufmann's html-to-markdown](https://github.com/JohannesKaufmann/html-to-markdown) that does the heavy lifting behind the scene. -## Install Source +### Similar Projects -To install the source code instead: +- [turndown (js)](https://github.com/domchristie/turndown), a very good library written in javascript. +- [lunny/html2md](https://github.com/lunny/html2md), which is using [regex instead of goquery](https://stackoverflow.com/a/1732454), which exhibits a few edge cases which prompted `github.com/JohannesKaufmann/html-to-markdown` +- [jaytaylor/html2text](https://github.com/jaytaylor/html2text), which is not converting to markdown but plain text. -``` -go install github.com/suntong/html2md@latest +## Download/install binaries + +- The latest binary executables are available +as the result of the Continuous-Integration (CI) process. +- I.e., they are built automatically right from the source code at every git release by [GitHub Actions](https://docs.github.com/en/actions). +- There are two ways to get/install such binary executables + * Using the **binary executables** directly, or + * Using **packages** for your distro + +### The binary executables + +- The latest binary executables are directly available under +https://github.com/suntong/html2md/releases/latest +- Pick & choose the one that suits your OS and its architecture. E.g., for Linux, it would be the `html2md_verxx_linux_amd64.tar.gz` file. +- Available OS for binary executables are + * Linux + * Mac OS (darwin) + * Windows +- If your OS and its architecture is not available in the download list, please let me know and I'll add it. +- The manual installation is just to unpack it and move/copy the binary executable to somewhere in `PATH`. For example, + +``` sh +tar -xvf html2md_*_linux_amd64.tar.gz +sudo mv -v html2md_*_linux_amd64/html2md /usr/local/bin/ +rmdir -v html2md_*_linux_amd64 ``` -# Credits & Authors +### Distro package -## Credits +- [Packages available for Linux distros](https://cloudsmith.io/~suntong/repos/repo/packages/) are + * [Alpine Linux](https://cloudsmith.io/~suntong/repos/repo/setup/#formats-alpine) + * [Debian](https://cloudsmith.io/~suntong/repos/repo/setup/#formats-deb) + * [RedHat](https://cloudsmith.io/~suntong/repos/repo/setup/#formats-rpm) -- [Johannes Kaufmann's html-to-markdown](github.com/JohannesKaufmann/html-to-markdown) that does the heavy lifting behind the scene. +The repo setup instruction url has been given above. +For example, for [Debian](https://cloudsmith.io/~suntong/repos/repo/setup/#formats-deb) -- -## Similar Projects +### Debian package -- [turndown (js)](https://github.com/domchristie/turndown), a very good library written in javascript. -- [lunny/html2md](https://github.com/lunny/html2md), which is using [regex instead of goquery](https://stackoverflow.com/a/1732454), which exhibits a few edge cases which prompted `github.com/JohannesKaufmann/html-to-markdown` -- [jaytaylor/html2text](https://github.com/jaytaylor/html2text), which is not converting to markdown but plain text. -## Author(s) & Contributor(s) +```sh +curl -1sLf \ + 'https://dl.cloudsmith.io/public/suntong/repo/setup.deb.sh' \ + | sudo -E bash + +# That's it. You then can do your normal operations, like + +sudo apt-get update +apt-cache policy html2md + +sudo apt-get install -y html2md +``` + +## Install Source + +To install the source code instead: + +``` +go install github.com/suntong/html2md +``` + +## Author Tong SUN ![suntong from cpan.org](https://img.shields.io/badge/suntong-%40cpan.org-lightgrey.svg "suntong from cpan.org") +_Powered by_ [**WireFrame**](https://github.com/go-easygen/wireframe) [![PoweredBy WireFrame](https://github.com/go-easygen/wireframe/blob/master/PoweredBy-WireFrame-Y.svg)](http://godoc.org/github.com/go-easygen/wireframe) -_Powered by_ [**WireFrame**](https://github.com/go-easygen/wireframe), the _one-stop wire-framing solution_ for Go cli based projects, from start to deploy. +the _one-stop wire-framing solution_ for Go cli based projects, from _init_ to _deploy_. + +## Contributors ✨ + +Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): + + + + + + + + +

suntong
💻 🤔 🎨 🔣 ⚠️ 🐛 📖 📝 💡 ✅ 🔧 📦 👀 💬 🚧 🚇
+ + + + + -All patches welcome. +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! -- cgit v1.2.3