github.com/cpuguy83/go-md2man/v2 v2.0.2: md2man.Render

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2
Demonstrate these symbols/APIs:
  - md2man.Render

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:b15f45a7f4037e31de0e0836c58aaef2989987416a834fffb793bd2cd629ac38","contract":["md2man.Render converts markdown document with title and metadata into roff title header","md2man.Render converts markdown section headings to roff SH and SS section headers","md2man.Render converts bold, italic, and inline code formatting to roff font escape sequences","md2man.Render converts fenced code blocks to roff indented nofill blocks","md2man.Render converts markdown lists to roff indented paragraphs","md2man.Render outputs roff hyphenation disable macro by default"],"goal":"verify pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2","kind":"HOW","packages":["pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2"],"schemaVersion":1,"symbols":["md2man.Render"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","languageVersion":"1.26.6","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2"],"schemaVersion":1,"subject":"pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2","symbols":["md2man.Render"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/cpuguy83/go-md2man/v2 v2.0.2

require github.com/russross/blackfriday/v2 v2.1.0 // indirect

github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/cpuguy83/go-md2man/v2@v2.0.2"
  ],
  "symbols": [
    "md2man.Render"
  ]
}

package main

import (
	"fmt"
	"os"
	"strings"

	"github.com/cpuguy83/go-md2man/v2/md2man"
)

func main() {
	if err := runTests(); err != nil {
		fmt.Fprintf(os.Stderr, "Contract test failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("All contract tests passed successfully.")
}

func runTests() error {
	// 1. Test markdown title and metadata converted into troff title header (.TH)
	docHeader := `# MYCMD 1 "August 2026" "Version 1.0.0" "User Commands"

## NAME
mycmd - sample cli command
`
	outHeader := md2man.Render([]byte(docHeader))
	outHeaderStr := string(outHeader)

	if !strings.Contains(outHeaderStr, `.TH MYCMD 1 "August 2026" "Version 1.0.0" "User Commands"`) {
		return fmt.Errorf("expected .TH header with title, section, date, version, manual, got:\n%s", outHeaderStr)
	}
	if !strings.Contains(outHeaderStr, ".nh") {
		return fmt.Errorf("expected .nh disable hyphenation macro in header, got:\n%s", outHeaderStr)
	}

	// 2. Test markdown headings converted to section (.SH) and subsection (.SS) headers
	docSections := `## SECTION ONE
Section one content.

### SUBSECTION A
Subsection content.
`
	outSections := md2man.Render([]byte(docSections))
	outSectionsStr := string(outSections)

	if !strings.Contains(outSectionsStr, ".SH SECTION ONE") {
		return fmt.Errorf("expected '.SH SECTION ONE', got:\n%s", outSectionsStr)
	}
	if !strings.Contains(outSectionsStr, ".SS SUBSECTION A") {
		return fmt.Errorf("expected '.SS SUBSECTION A', got:\n%s", outSectionsStr)
	}

	// 3. Test inline formatting: bold, italic, and code spans
	docFormatting := `Use **bold text**, *italic text*, and ` + "`inline code`" + ` in description.`
	outFormatting := md2man.Render([]byte(docFormatting))
	outFormattingStr := string(outFormatting)

	fontBold := string([]byte{0x5c, 'f', 'B'})
	fontItalic := string([]byte{0x5c, 'f', 'I'})
	fontPrev := string([]byte{0x5c, 'f', 'P'})
	fontRoman := string([]byte{0x5c, 'f', 'R'})
	fontConst := string([]byte{0x5c, 'f', 'C'})

	if !strings.Contains(outFormattingStr, fontBold+"bold text"+fontPrev) {
		return fmt.Errorf("expected bold formatting, got:\n%s", outFormattingStr)
	}
	if !strings.Contains(outFormattingStr, fontItalic+"italic text"+fontPrev) {
		return fmt.Errorf("expected italic formatting, got:\n%s", outFormattingStr)
	}
	if !strings.Contains(outFormattingStr, fontBold+fontConst+"inline code"+fontRoman) {
		return fmt.Errorf("expected code formatting, got:\n%s", outFormattingStr)
	}

	// 4. Test fenced code blocks converted to roff no-fill indented blocks (.RS/.RE/.nf/.fi)
	docCodeBlock := "```\nfoo --flag=value\nbar\n```"
	outCodeBlock := md2man.Render([]byte(docCodeBlock))
	outCodeBlockStr := string(outCodeBlock)

	if !strings.Contains(outCodeBlockStr, ".RS") || !strings.Contains(outCodeBlockStr, ".RE") || !strings.Contains(outCodeBlockStr, ".nf") || !strings.Contains(outCodeBlockStr, ".fi") {
		return fmt.Errorf("expected .RS, .RE, .nf, and .fi around code block, got:\n%s", outCodeBlockStr)
	}
	if !strings.Contains(outCodeBlockStr, "foo --flag=value") {
		return fmt.Errorf("expected code block content preserved, got:\n%s", outCodeBlockStr)
	}

	// 5. Test bulleted list converted to indented paragraphs (.IP)
	docList := `* Option one
* Option two
`
	outList := md2man.Render([]byte(docList))
	outListStr := string(outList)

	if !strings.Contains(outListStr, ".IP \\(bu 2") {
		return fmt.Errorf("expected bullet list macro '.IP \\(bu 2', got:\n%s", outListStr)
	}
	if !strings.Contains(outListStr, "Option one") || !strings.Contains(outListStr, "Option two") {
		return fmt.Errorf("expected list items preserved, got:\n%s", outListStr)
	}

	// 6. Test minimal document handling and hyphenation disabling
	emptyOut := md2man.Render([]byte(""))
	if string(emptyOut) != ".nh\n" {
		return fmt.Errorf("expected .nh\\n for empty document, got: %q", string(emptyOut))
	}

	return nil
}