Skip to content
starpkgPublic

About

πŸ“ Starlark module built on Goldmark for Markdown to HTML conversion with support for CommonMark, GitHub-style emojis, tables, task lists, and more.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

26 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ“ markdown β€” Markdown to HTML for Starlark

Go Reference codecov binary footprint

Convert Markdown to HTML from Starlark, built on goldmark. CommonMark-compliant with opt-in extensions (tables, task lists, strikethrough, autolinks, footnotes, definition lists, typographer, emoji) and configurable rendering (hard wraps, auto heading IDs).

Overview

This is a starpkg module: starpkg provides support for necessary local operations plus simple abstractions over common online services, for ease of use. Markdown rendering is a purely local capability β€” it runs entirely in-process (no network, no filesystem), so a script can turn untrusted Markdown into HTML without reaching out to anything.

  • Two builtins β€” convert renders in one call; create_converter builds a reusable converter with rendering options frozen in.
  • Secure by default β€” raw HTML in the source is filtered out unless you opt in with unsafe=True, and renderer panics are recovered into errors.
  • Bounded work β€” a max_input_bytes cap rejects oversized input before it reaches the renderer, and a max_convert_time cap bounds a single conversion's wall-clock time (goldmark's nested parsing is ~O(nΒ²), so an input under the byte cap can still spin). Both are host-only.

For the complete per-builtin reference β€” signatures, parameters, returns, errors, examples β€” and the configuration accessors, see docs/API.md.

Installation

go get github.com/starpkg/markdown

Go floor: this module requires Go 1.22+. It tracks the latest goldmark (no downgrade) for upstream security and correctness fixes; the recent goldmark releases raise their own Go floor, so this module relaxes its floor to match (per ENG-09 SEP β€” a module may raise its floor when a dependency requires it, like the email module).

Quickstart

Wire the module into a Starlet interpreter, then load("markdown", …) from a script:

package main

import (
    "fmt"

    "github.com/1set/starlet"
    "github.com/starpkg/markdown"
)

func main() {
    mod := markdown.NewModule()
    interpreter := starlet.NewWithLoaders(nil, nil, starlet.ModuleLoaderMap{
        "markdown": mod.LoadModule(),
    })

    script := `
load("markdown", "convert")
html = convert(text="# Hello World\n\nThis is **bold** text.")
print(html)
`
    if _, err := interpreter.RunScript([]byte(script), nil); err != nil {
        fmt.Printf("Error: %v\n", err)
    }
}

From Starlark, render in one call or build a reusable converter:

load("markdown", "convert", "create_converter")

# One-shot conversion.
html = convert(text="# Hello World\n\nThis is **bold** text.")
print(html)
# <h1 id="hello-world">Hello World</h1>
# <p>This is <strong>bold</strong> text.</p>

# Reusable converter with preset options.
to_html = create_converter(table=False, linkify=False, hard_wraps=True)
print(to_html("# Title\n\nFirst line\nSecond line"))

Starlark API at a glance

Top-level builtins (load("markdown", …)):

  • convert(text, unsafe?, heading_id?, linkify?, table?, task_list?, strikethrough?, footnote?, definition?, typograph?, emoji?, hard_wraps?) β€” render Markdown to HTML in one call (text accepts string / bytes / None).
  • create_converter(unsafe?, heading_id?, linkify?, table?, task_list?, strikethrough?, footnote?, definition?, typograph?, emoji?, hard_wraps?) β€” build a reusable custom_converter with options frozen in.

Converter object:

  • custom_converter(text) β€” the callable returned by create_converter; renders a Markdown string with the preset options (no further keywords).

Configuration accessors:

  • get_max_input_bytes() β€” read the input-size cap. Host-only: set_max_input_bytes is intentionally not exposed, so a script cannot disable or widen the DoS limit β€” only the host can, in Go or via the env var.
  • get_max_convert_time() β€” read the per-conversion wall-clock time cap (seconds; 0 = no module limit). Also host-only: no set_max_convert_time.

See docs/API.md for the full signatures, return values, errors, the shared rendering-option table, and examples of every builtin above.

Configuration

The module's options β€” max_input_bytes (input size) and max_convert_time (per-conversion wall-clock time; goldmark's nested parsing is ~O(nΒ²) so size alone doesn't bound CPU) β€” are both host-only, configured via the MARKDOWN_MAX_INPUT_BYTES / MARKDOWN_MAX_CONVERT_TIME environment variables or the Go host (a script can read them with get_max_input_bytes but cannot change it β€” set_max_input_bytes is not generated). See the Configuration section of docs/API.md for the full option table, default, accessors, and details.

License

This project is licensed under the MIT License β€” see the LICENSE file for details.

About

πŸ“ Starlark module built on Goldmark for Markdown to HTML conversion with support for CommonMark, GitHub-style emojis, tables, task lists, and more.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages