rembed

README

rembed

rembed embeds README-style markdown into an application and renders it as a single standalone HTML page with inline CSS, inline JavaScript, syntax highlighting, and theme switching.

The package currently lives inside the nodeman repository so it can be extracted into its own repository with minimal cleanup later.

What It Does

• render embedded markdown as polished standalone HTML
• inline referenced assets such as assets/logo.svg as data URLs
• rewrite relative links to a repository or other absolute base URL
• write versioned local docs that open directly with file://
• open generated docs in the default browser

Example

package main

import (
	_ "embed"
	"log"

	"github.com/arcmantle/rembed"
)

//go:embed README.md
var embeddedREADME []byte

func main() {
	html, err := rembed.RenderHTML(string(embeddedREADME), rembed.WriteOptions{
		Title:      "My App Documentation",
		Version:    "dev",
		SourcePath: "README.md",
		LinkBaseURL: rembed.GitHubRawBaseURL("owner", "repo", "main"),
	})
	if err != nil {
		log.Fatal(err)
	}

	_ = html
}

Typical README Flow

docPath, err := rembed.WriteDocsWithOptions(baseDir, string(embeddedREADME), rembed.WriteOptions{
	Title:      "My App Documentation",
	Version:    version,
	SourcePath: "embedded README.md",
	Force:      force,
	InlineAssets: map[string]rembed.InlineAsset{
		"assets/logo.svg": {
			Data:     embeddedLogo,
			MIMEType: "image/svg+xml",
		},
	},
	LinkBaseURL: rembed.GitHubRawBaseURL("owner", "repo", "main"),
})

Web Bundle

The standalone page UI is built from web/ and embedded from webdist/.

To rebuild it:

cd rembed/web
pnpm install
pnpm build

Documentation

Overview

Package rembed renders embedded README-style markdown as a standalone HTML page.

The package is designed for applications that embed markdown content at build time, optionally inline referenced assets, rewrite relative links to an external source, and either write or serve a single self-contained HTML file.

Index

• func GitHubRawBaseURL(owner, repo, ref string) string
• func InlineReferencedAssets(markdown string, assets map[string]InlineAsset) string
• func OpenInBrowser(path string) error
• func RenderHTML(markdown string, opts WriteOptions) ([]byte, error)
• func RewriteRelativeLinks(markdown, baseURL string) string
• func RewriteRelativeLinksForGitHub(markdown, owner, repo, ref string) string
• func WriteDocs(baseDir, markdown string) (string, error)
• func WriteDocsWithOptions(baseDir, markdown string, opts WriteOptions) (string, error)
• func WriteVersionedDocs(baseDir, version string, markdown []byte, title, sourcePath string, force bool) (string, error)
• type InlineAsset
• type WriteOptions

Functions

func GitHubRawBaseURL

func GitHubRawBaseURL(owner, repo, ref string) string

GitHubRawBaseURL builds a raw.githubusercontent.com base URL for a repo ref.

If ref is empty, it defaults to "main".

func InlineReferencedAssets

func InlineReferencedAssets(markdown string, assets map[string]InlineAsset) string

InlineReferencedAssets replaces matching markdown/HTML asset links with data URLs.

Asset map keys should be repository-relative or markdown-relative paths like "assets/logo.svg" or "./assets/logo.svg".

func OpenInBrowser

func OpenInBrowser(path string) error

OpenInBrowser opens a file path in the user's default browser.

func RenderHTML

func RenderHTML(markdown string, opts WriteOptions) ([]byte, error)

RenderHTML renders markdown content into a standalone HTML page in memory.

func RewriteRelativeLinks

func RewriteRelativeLinks(markdown, baseURL string) string

RewriteRelativeLinks rewrites relative markdown and HTML links to absolute URLs.

baseURL must be an absolute URL and should usually end with '/'.

func RewriteRelativeLinksForGitHub

func RewriteRelativeLinksForGitHub(markdown, owner, repo, ref string) string

RewriteRelativeLinksForGitHub rewrites relative links using a GitHub raw-content base URL.

func WriteDocs

func WriteDocs(baseDir, markdown string) (string, error)

WriteDocs writes markdown content to a standalone docs page using sensible defaults.

It writes to <baseDir>/docs/dev/index.html with title "Documentation".

func WriteDocsWithOptions

func WriteDocsWithOptions(baseDir, markdown string, opts WriteOptions) (string, error)

WriteDocsWithOptions writes markdown content to versioned standalone docs.

This is a convenience wrapper for consumers that embed their own README string.

func WriteVersionedDocs

func WriteVersionedDocs(baseDir, version string, markdown []byte, title, sourcePath string, force bool) (string, error)

WriteVersionedDocs writes a standalone docs page to <baseDir>/docs/<version>/index.html. The resulting HTML has inline CSS, inline app JS, and inline markdown payload, so it can be opened directly with file:// without running a local web server.

Types

type InlineAsset

type InlineAsset struct {
	Data []byte
	// MIMEType is optional. When empty, the type is inferred from the asset path.
	MIMEType string
}

InlineAsset describes a binary asset that may be inlined into markdown links.

type WriteOptions

type WriteOptions struct {
	// Version controls the docs output folder name. Empty defaults to "dev".
	Version string
	// Title sets the rendered page heading. Empty defaults to "Documentation".
	Title string
	// SourcePath is shown in page metadata. Empty defaults to "embedded markdown".
	SourcePath string
	// Force regenerates docs even if the destination file already exists.
	Force bool
	// InlineAssets replaces matching markdown and HTML asset references with data URLs.
	InlineAssets map[string]InlineAsset
	// LinkBaseURL rewrites relative markdown and HTML links against an absolute base URL.
	LinkBaseURL string
}

WriteOptions configures standalone docs generation from markdown content.