Skip to content

Commit

Permalink
readme: improve documentation for plugins
Browse files Browse the repository at this point in the history
  • Loading branch information
JohannesKaufmann committed Nov 6, 2024
1 parent 0f887f8 commit 099f6f2
Show file tree
Hide file tree
Showing 12 changed files with 125 additions and 29 deletions.
Binary file added .github/images/autocomplete_register.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
89 changes: 61 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,62 +2,47 @@

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](#golang-library) or a quick [CLI command](#cli---using-it-on-the-command-line). Try the [demo](https://html-to-markdown.com/demo) to see it in action!
Use the fully extendable [Golang library](#golang-library) or a quick [CLI command](#cli---using-it-on-the-command-line). Alternatively, try the [Online Demo](https://html-to-markdown.com/demo) or [REST API](https://html-to-markdown.com/api) to see it in action!

Here are some _cool features_:

- **Bold & Italic:** Supports bold and italic—even within single words.

![](./.github/point_bold_italic.png)
![](./.github/images/point_bold_italic.png)

- **List:** Handles ordered and unordered lists with full nesting support.

![](./.github/point_list.png)
![](./.github/images/point_list.png)

- **Blockquote:** Blockquotes can include other elements, with seamless support for nested quotes.

![](./.github/point_blockquote.png)
![](./.github/images/point_blockquote.png)

- **Inline Code & Code Block:** Correctly handles backticks and multi-line code blocks, preserving code structure.

![](./.github/point_code.png)
![](./.github/images/point_code.png)

- **Link & Image:** Properly formats multi-line links, adding escapes for blank lines where needed.

![](./.github/point_link_image.png)
![](./.github/images/point_link_image.png)

- **Smart Escaping:** Escapes special characters only when necessary, to avoid accidental Markdown rendering.
🗒️ [ESCAPING.md](/ESCAPING.md)

![](./.github/point_escaping.png)
![](./.github/images/point_escaping.png)

- **Remove/Keep HTML:** Choose to strip or retain specific HTML tags for ultimate control over output.

![](./.github/point_wrapper.png)
![](./.github/images/point_wrapper.png)

- **Plugins:** Easily extend with plugins. Or create custom ones to enhance functionality.

![](./.github/point_strikethrough.png)
![](./.github/images/point_strikethrough.png)

---

---

> [!WARNING]
> This is an **early experimental version** of the library.
>
> We encourage testing and bug reporting. However, please note:
>
> - Not production-ready
> - Default options are well-tested, but custom configurations have limited coverage
> - Functionality is currently restricted
> - Focus is on stabilization and core features
> - No compatibility guarantee
> - Only use `htmltomarkdown.ConvertString()` and `htmltomarkdown.ConvertNode()` from the root package. They are _unlikely_ to change.
> - Other functions and nested packages are _very like_ to change.
---

## Golang Library

### Installation
Expand All @@ -68,6 +53,9 @@ 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](https://github.com/JohannesKaufmann/html-to-markdown/tree/v1).
### Usage

[![Go V2 Reference](https://pkg.go.dev/badge/github.com/JohannesKaufmann/html-to-markdown/v2.svg)](https://pkg.go.dev/github.com/JohannesKaufmann/html-to-markdown/v2)
Expand Down Expand Up @@ -96,7 +84,7 @@ func main() {

- 🧑‍💻 [Example code, basics](/examples/basics/main.go)

The function `htmltomarkdown.ConvertString()` is just a small wrapper around `converter.NewConverter()` and `commonmark.NewCommonmarkPlugin()`. If you want more control, use the following:
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:

```go
package main
Expand Down Expand Up @@ -139,7 +127,48 @@ func main() {
### Plugins

TODO: info about plugins
#### Published Plugins

These are the plugins located in the [plugin folder](/plugin):

| Name | Description |
| --------------------- | ------------------------------------------------------------------------------------ |
| Base | Implements basic shared functionality (e.g. removing nodes) |
| Commonmark | Implements Markdown according to the [Commonmark Spec](https://spec.commonmark.org/) |
| | |
| GitHubFlavored | _planned_ |
| TaskListItems | _planned_ |
| Strikethrough | Converts `<strike>`, `<s>`, and `<del>` 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.

![](./.github/images/autocomplete_register.png)

- 🧑‍💻 [Example code, register](/examples/register/main.go)

2. _Optional:_ Package your logic into a **plugin** and publish it.

- 🗒️ [WRITING_PLUGINS.md](/WRITING_PLUGINS.md)

---

Expand Down Expand Up @@ -199,10 +228,14 @@ _(The cli does not support every option yet. Over time more customization will b
### 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.

- Don't like the **defaults** that the library uses? You can use `PriorityEarly` to run you logic _earlier_ than others.

- 🧑‍💻 [Example code, register](/examples/register/main.go)

- If you believe that you logic could also benefit others, you can package it up into a **plugin**.

🗒️ [WRITING_PLUGINS.md](/WRITING_PLUGINS.md)
- 🗒️ [WRITING_PLUGINS.md](/WRITING_PLUGINS.md)

### Bugs

Expand Down
63 changes: 63 additions & 0 deletions examples/register/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
package main

import (
"fmt"
"log"
"strconv"
"strings"

"github.com/JohannesKaufmann/dom"
"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"
"golang.org/x/net/html"
)

func main() {
input := `
<h2>
<span>Golang</span>
<star-rating count="5">five stars</star-rating>
</h2>
<p>Build simple, secure, <i>scalable</i> systems with Go</p>
`

conv := converter.NewConverter(
converter.WithPlugins(
base.NewBasePlugin(),
commonmark.NewCommonmarkPlugin(),
),
)

// Here we a registering a custom *renderer* for <star-rating> and pass in our function.
conv.Register.RendererFor("star-rating", converter.TagTypeInline, renderStarRating, converter.PriorityStandard)

markdown, err := conv.ConvertString(input)
if err != nil {
log.Fatal(err)
}
fmt.Println(markdown)
// ## Golang ⭐️⭐️⭐️⭐️⭐️
//
// Build simple, secure, *scalable* systems with Go
}

func renderStarRating(ctx converter.Context, w converter.Writer, node *html.Node) converter.RenderStatus {
// The "github.com/JohannesKaufmann/dom" package provides helper functions
// to interact with the html node, like getting the attribute "count".
rawCount := dom.GetAttributeOr(node, "count", "0")
count, _ := strconv.Atoi(rawCount)

rating := strings.Repeat("⭐️", count)

// Write the content
w.WriteString(rating)

// w.WriteString(" (")
// ctx.RenderChildNodes(ctx, w, node)
// w.WriteString(")")

// And then return whether it was a *success*
// or if the next renderer should be tried.
return converter.RenderSuccess
}
2 changes: 1 addition & 1 deletion plugin/strikethrough/strikethrough_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ func TestNewStrikethroughPlugin(t *testing.T) {
expected: `~~Text~~`,
},
{
desc: "with spaces inside",
desc: "with tilde characters inside",
input: `<p><s>~~A~~B~~</s></p>`,
expected: `~~\~\~A\~\~B\~\~~~`,
},
Expand Down

0 comments on commit 099f6f2

Please sign in to comment.