README
¶
ocidoc-render
ocidoc-render renders OCIDoc Markdown
and sanitizes HTML fragments for safe embedding in a user interface.
It accepts GitHub-Flavored Markdown, removes active content, validates local bundle-relative URLs, normalizes external links and controls whether external media resources may load.
The package returns an HTML fragment, not a complete HTML document. Embed its output in a page that supplies the surrounding document structure and Content Security Policy.
Install
go get github.com/ocidoc/ocidoc-render@v0.1.0
Render Markdown
DocumentPath is required to resolve local URLs
relative to the OCIDoc document being rendered.
fragment, err := render.Markdown(markdown, render.Options{
DocumentPath: "docs/README.md",
})
if err != nil {
return err
}
// Embed fragment only after checking err.
Raw Markdown HTML is allowed through Goldmark only so that the sanitizer can apply one policy to both Markdown-generated and raw HTML. It does not make the output trusted: scripts, event handlers, styles, dangerous URL schemes and disallowed elements are removed.
Sanitize existing HTML
fragment, err := render.HTML(html, render.Options{
DocumentPath: "README.md",
ExternalAssets: render.ExternalAssetsBlock,
})
if err != nil {
return err
}
ExternalAssetsBlock removes HTTP(S) subresource URLs from images,
audio and video while preserving ordinary navigation links.
ExternalAssetsAllow is the default and preserves those subresource URLs.
Scope
This package is intentionally a renderer and sanitizer, not a browser sandbox. Consumers should still apply an appropriate Content Security Policy, serve output with a restrictive MIME type and avoid granting it privileged origin access.
For the OCIDoc format and the full documentation, see ocidoc.org.
Documentation
¶
Overview ¶
Package render converts Markdown or raw HTML into a sanitized HTML fragment safe to embed in a trusted page template.
It owns the reusable, document-format-agnostic part of that security boundary: Markdown-to-HTML conversion, the explicit allowlist sanitizer, dangerous URL scheme rejection, and native audio/video/source/track handling. Markdown and HTML both return a fragment, not a complete HTML document; routing, local asset serving and the trusted outer page template stay the hosting application's own job, since those are inherently specific to how each application is built and served. ContentSecurityPolicy and SecurityHeaders provide a ready-to-use reference policy for the one full-page concern that pairs directly with what the sanitizer allows through, so a consumer is not forced to invent an equivalent CSP from scratch, but using them is optional.
This package has no dependency on OCIDoc registry, store or CLI packages; it depends on github.com/ocidoc/ocidoc-go/spec only for spec.ValidateBundlePath, the same portable bundle-path rule OCIDoc artifacts already use, so a local URL is judged "valid" by the exact rule that decided whether the file it points to could exist in an OCIDoc artifact in the first place.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContentSecurityPolicy ¶
func ContentSecurityPolicy(mode ExternalAssets) string
ContentSecurityPolicy returns the reference deny-by-default CSP for a page that embeds this package's sanitized fragment output, scoped by mode: under ExternalAssetsBlock, image and media sources are same-origin only matching the fragment itself never containing an external subresource URL in that mode.
A caller is free to design its own full-page policy instead - this is a ready-to-use default paired with what the sanitizer actually allows through, not a requirement.
func HTML ¶
HTML sanitizes raw HTML source to a safe HTML fragment: the explicit document allowlist, then URL classification and media/link normalization.
WithUnsafe (Markdown's own raw-HTML passthrough) does not make its output trusted - this is the actual sanitization step, and every caller must run it before that output reaches anything.
Example ¶
fragment, err := HTML([]byte(
`<p>Read <a href="https://example.com">the guide</a>.</p><img src="https://example.com/logo.svg">`),
Options{
DocumentPath: "README.md",
ExternalAssets: ExternalAssetsBlock,
},
)
if err != nil {
panic(err)
}
fmt.Print(string(fragment))
Output: <p>Read <a href="https://example.com" rel="noopener noreferrer">the guide</a>.</p><img/>
func Markdown ¶
Markdown renders Markdown source to a sanitized HTML fragment: Goldmark conversion (raw HTML passthrough enabled) followed by the same sanitizer and URL/media policy HTML applies directly.
Example ¶
fragment, err := Markdown([]byte("# Guide\n\n<script>alert(1)</script>"), Options{
DocumentPath: "docs/README.md",
})
if err != nil {
panic(err)
}
fmt.Print(string(fragment))
Output: <h1>Guide</h1>
func SecurityHeaders ¶
func SecurityHeaders(header http.Header, mode ExternalAssets)
SecurityHeaders sets the reference response headers for a page that embeds this package's sanitized fragment output: ContentSecurityPolicy plus Referrer-Policy, X-Content-Type-Options and X-Frame-Options.
As with ContentSecurityPolicy itself, a caller may set these as-is, adapt them or build an entirely different policy - nothing else in this package depends on them being used.
Types ¶
type ExternalAssets ¶
type ExternalAssets string
ExternalAssets controls whether HTTP/HTTPS subresources (images, audio, video, source, track, poster) outside the document itself are left in place or stripped. It never affects navigation links (<a href>), only subresource loads.
const ( // ExternalAssetsAllow preserves HTTP(S) document subresources. ExternalAssetsAllow ExternalAssets = "allow" // ExternalAssetsBlock removes HTTP(S) document subresources. ExternalAssetsBlock ExternalAssets = "block" )
type Options ¶
type Options struct {
// DocumentPath is the source document's own bundle-relative path,
// used to resolve relative local URLs (images, links, media) against its directory.
// Required: local URL resolution has no other frame of reference.
DocumentPath string
// ExternalAssets defaults to ExternalAssetsAllow when empty.
ExternalAssets ExternalAssets
}
Options controls Markdown and HTML.
Source Files