harticle

README

go-harticle

Package harticle provides an http.Handler middleware to render harticle to HTML, for the Go programming language.

Documention

Online documentation, which includes examples, can be found at: http://godoc.org/codeberg.org/reiver/go-harticle

Example

Here is an example of using harticle.Handler to wrap another handler, to provide mardown to HTML rendering.

import "codeberg.org/reiver/go-harticle"

// ...

var handler http.Handler = ...

handler = harticle.Wrap(handler, harticle.SimpleRenderer) // <---------

err := http.ListenAndServe(":8080", handler)
if nil != err {
	return err
}

Import

To import package harticle use import code like the following:

import "codeberg.org/reiver/go-harticle"

Installation

To install package harticle do the following:

GOPROXY=direct go get codeberg.org/reiver/go-harticle

Author

Package harticle was written by Charles Iliya Krempeaux

Documentation

Index

• Constants
• func ExtractCategories(hart string) []string
• func ExtractTitle(hart string) string
• func SanitizeBytes(html []byte) []byte
• func SanitizeString(html string) string
• func TransformToActivity(writer io.Writer, hart []byte)
• func Wrap(subHandler http.Handler) http.Handler
• func WrapWithHTMLRenderer(subHandler http.Handler, htmlrenderer HTMLRenderer) http.Handler
• type Author
  • func ExtractAuthors(hart string) []Author
• type HTMLRenderer

Constants

const FileExtension string = ".hart"

FileExtension is constant for the file-extension used for harticle files.

Here is an example of a harticle file-name that has the ".hart" file-extension:

readme.hart

const MediaType string = "text/article+html"

MediaType is a constant for the media-type used for harticle content.

Note that the value of the HTTP Content-Type response header and the HTTP Accept request header both use media-types.

Functions

func ExtractCategories

func ExtractCategories(hart string) []string

func ExtractTitle

func ExtractTitle(hart string) string

ExtractTitle extracts the the 'title' from harticle data.

For example, if the harticle data is:

<article>
	<h1>Supercalifragilisticexpialidocious</h1>
	<p>
		It's supercalifragilisticexpialidocious.
		<br />
		Even though the sound of it is something quite atrocious.
		<br />
		If you say it loud enough you'll always sound precocious.
	</p>
</article>

Then the extracted title is:

"Supercalifragilisticexpialidocious"

The title is the first <h1>, <h2>, <h3>, <h4>, <h5>, or <h6>.

func SanitizeBytes

func SanitizeBytes(html []byte) []byte

SanitizeBytes returns the sanitized version of the HTML that is passed to it.

For example:

var html []byte = []byte(`One Two <script>alert("Hello!")</script> Three`)

sanitizedHTML := harticle.SanitizeBytes(html)

See also: SanitizeString

func SanitizeString

func SanitizeString(html string) string

SanitizeString returns the sanitized version of the HTML that is passed to it.

For example:

var html string = `One Two <script>alert("Hello!")</script> Three`

sanitizedHTML := harticle.SanitizeString(html)

See also: SanitizeBytes

func TransformToActivity

func TransformToActivity(writer io.Writer, hart []byte)

TransformToActivity transforms harticle data to activity data (i.e., ActivityPub / ActivityStreams data).

func Wrap

func Wrap(subHandler http.Handler) http.Handler

Wrap provides http.Handler middleware. It wraps another http.Handler and renders harticle as HTML or ActivityPub/ActivityStreams under the correct conditions.

The correct conditions for rendering harticle as HTML or ActivityPub/ActivityStreams is when the nested http.Handler returns something with a `Content-Type` that includes the media-type `text/article+html` AND the `Accept` header in the HTTP request does NOT contain `text/article+html`.

func WrapWithHTMLRenderer

func WrapWithHTMLRenderer(subHandler http.Handler, htmlrenderer HTMLRenderer) http.Handler

WrapWithHTMLRenderer provides http.Handler middleware. It wraps another http.Handler and renders harticle, using a custom [Renderer], as HTML or ActivityPub/ActivityStreams under the correct conditions.

The correct conditions for rendering harticle as HTML or ActivityPub/ActivityStreams is when the nested http.Handler returns something with a `Content-Type` that includes the media-type `text/harticle` AND the `Accept` header in the HTTP request does NOT contain `text/harticle`.

Types

type Author

type Author struct {
	Name      string
	Reference string
}

Author is used with ExtractAuthors.

func ExtractAuthors

func ExtractAuthors(hart string) []Author

ExtractAuthors extracts the the 'authors' from harticle data. There can be zero, one, or many authors in harticle data.

In the harticle, author data looks like this.

<a rel="author" href="http://example.com/~joeblow">Jow Blow</a>

The author-name is: Joe Blow / The author-reference is: http://example.com/~joeblow

The thing about that HTML archor element (<a>) that makes it an author is the presense of the rel-author code.

type HTMLRenderer

type HTMLRenderer interface {
	RenderHTML(io.Writer, []byte) error
}

HTMLRenderer is something that is given the harticle data, it writes the rendered HTML to an io.Writer.

See also: WrapWithHTMLRenderer and [SimpleRenderer].

var SimpleHTMLRenderer HTMLRenderer = internalSimpleHTMLRenderer{}

SimpleHTMLRenderer is the [Renderer] that is used when someone calls Wrap (rather than [WrapWithRenderer]).

If you are looking to create your own custom renderer, look at the source-code for SimpleHTMLRenderer to see an example of one, and to help you understand how they work.