@ui-doc/html-renderer

HTML renderer for UI-Doc that converts UI-Doc context objects into interactive HTML documentation pages. It implements the Renderer interface from @ui-doc/core and includes a built-in template engine with zero dependencies.

Overview

The HTML renderer provides:

- Template Engine - A lightweight, dependency-free template system with custom syntax
- Built-in Templates - Ready-to-use layouts, pages, and partials for documentation
- Asset Management - Pre-built CSS and JavaScript for documentation styling
- Extensibility - Custom templates and styling support

Installation

``bash
npm install @ui-doc/html-renderer @ui-doc/core
`

Quick Start

$3

`ts
import { HtmlRenderer, NodeParser } from '@ui-doc/html-renderer'

// Create a renderer instance
const renderer = new HtmlRenderer(NodeParser.init())

// Add templates
renderer.addLayout('default', {
source: 'inline',
content:





{{page:default}}


,
})

renderer.addPage('default', {
source: 'inline',
content:

{{var:title}}

`ts
import { UIDoc } from '@ui-doc/core'
import { HtmlRenderer, NodeParser, TemplateLoader } from '@ui-doc/html-renderer'
import { NodeFileSystem } from '@ui-doc/node'

const fileSystem = new NodeFileSystem()
const renderer = new HtmlRenderer(NodeParser.init())

// Load built-in templates
const templatePath = await fileSystem.assetLoader().packagePath(
TemplateLoader.TEMPLATES_PACKAGE,
)
await TemplateLoader.load({ renderer, fileSystem, templatePath })

// Create UI-Doc instance
const uidoc = new UIDoc({ renderer })

// Process source files
uidoc.sourceCreate('path/to/source.css', await fileSystem.fileRead('path/to/source.css'))

// Output documentation
await uidoc.output(async (file, content) => {
await fileSystem.fileWrite(./dist/${file}, content)
})

// Copy required assets
const assetLoader = fileSystem.assetLoader()
await assetLoader.copy('@ui-doc/html-renderer/ui-doc.min.css', './dist/ui-doc.css')
await assetLoader.copy('@ui-doc/html-renderer/ui-doc.min.js', './dist/ui-doc.js')
`

Template Syntax

The template engine uses double curly braces {{...}} for directives.

$3

Output values from the context:

`html


{{var:title}}

`html
{{if:showContent}}


This is visible when showContent is truthy

Supported comparison operators: ===, ==, !==, !=, <, <=, >, >=

`html
{{if:status === "active"}}
Active
{{/if}}

{{if:count > 5}}
More than 5 items
{{/if}}
`

$3

#### Array Loops

`html



{{for:items}}

• {{var:_loop.value}} (index: {{var:_loop.index}})

{{/for}}

• apple (index: 0)


• banana (index: 1)


• cherry (index: 2)

`html



{{for:colors}}

• {{var:_loop.key}}: {{var:_loop.value}}

{{/for}}

• red: #f00


• green: #0f0


• blue: #00f

`html

{{for:sections}}


Loop variables available in _loop:

- _loop.value - Current item value
- _loop.index - Current iteration index (0-based)
- _loop.key - Current key (for object loops)

$3

Render registered page templates with optional context switching:

`html

{{page}}


{{page:default}}


{{page:default page}}
`

$3

Include reusable template fragments:

`html

{{partial:nav-main}}


{{partial:section currentSection}}
`

$3

Output context as JSON for debugging:

`html

{{debug}}


{{debug:page}}
`

Template Types

$3

Define the overall HTML structure. A layout typically includes the , , and tags.

`ts
renderer.addLayout('default', {
source: 'my-layout.html',
content:





{{var:styles}}


{{page:default}}
{{var:scripts}}


,
})
`

$3

Define page-specific content structures:

`ts
renderer.addPage('default', {
source: 'my-page.html',
content:

`ts
renderer.addPartial('section', {
source: 'section.html',
content:

Use TemplateLoader to load templates from the file system:

`ts
import { TemplateLoader } from '@ui-doc/html-renderer'
import { NodeFileSystem } from '@ui-doc/node'

const fileSystem = new NodeFileSystem()

// Load templates from a directory
await TemplateLoader.load({
renderer,
fileSystem,
templatePath: './my-templates',
})
`

The loader expects this directory structure:

`text
my-templates/
layouts/
default.html
custom.html
pages/
default.html
index.html
partials/
nav.html
section.html
`

$3

The package includes ready-to-use templates:

`ts
const templatePath = await fileSystem.assetLoader().packagePath(
TemplateLoader.TEMPLATES_PACKAGE,
)
await TemplateLoader.load({ renderer, fileSystem, templatePath })
`

Built-in Assets

The package provides pre-built CSS and JavaScript for documentation styling.

$3

`bash


Full CSS

`bash


Full JavaScript

`ts
const assetLoader = fileSystem.assetLoader()

await assetLoader.copy(
'@ui-doc/html-renderer/ui-doc.min.css',
'./dist/ui-doc.css',
)
await assetLoader.copy(
'@ui-doc/html-renderer/ui-doc.min.js',
'./dist/ui-doc.js',
)
`

$3

The built-in templates use highlight.js for code syntax highlighting. Include it in your output:

`ts
await assetLoader.copy(
'@highlightjs/cdn-assets/styles/default.min.css',
'./dist/highlight.css',
)
await assetLoader.copy(
'@highlightjs/cdn-assets/highlight.min.js',
'./dist/highlight.js',
)
`

API Reference

$3

The main renderer class implementing the Renderer interface.

#### Constructor

`text
new HtmlRenderer(parser: Parser)
`

- parser - A Parser instance (typically NodeParser.init())

#### Methods

##### addLayout(name, layout)

Register a layout template.

`text
renderer.addLayout(name: string, layout: SourceInput): HtmlRenderer
`

- name - Unique identifier for the layout
- layout - Template source (object with source and content properties, or a Reader instance)
- Returns the renderer instance for chaining

##### addPage(name, page)

Register a page template.

`text
renderer.addPage(name: string, page: SourceInput): HtmlRenderer
`

- name - Unique identifier for the page
- page - Template source
- Returns the renderer instance for chaining

##### addPartial(name, partial)

Register a partial template.

`text
renderer.addPartial(name: string, partial: SourceInput): HtmlRenderer
`

- name - Unique identifier for the partial
- partial - Template source
- Returns the renderer instance for chaining

##### generate(context, layout?)

Generate HTML from a context object.

`text
renderer.generate(context: GenerateContext, layout?: string): string
`

- context - The UI-Doc context object to render
- layout - Optional layout name (defaults to 'default')
- Returns the generated HTML string

The GenerateContext includes:

- title - Document title
- page - Page context object
- assets - Array of asset objects with type, src, and optional attrs
- Additional properties from your UI-Doc configuration

##### page(name, context)

Render a specific page template with context.

`text
renderer.page(name: string, context: RenderContext): string
`

- name - Page template name (falls back to 'default' if not found)
- context - Context object for rendering
- Returns the rendered HTML string

##### partial(name, context?)

Render a specific partial template with optional context.

`text
renderer.partial(name: string, context?: RenderContext): string
`

- name - Partial template name (falls back to 'default' if not found)
- context - Optional context object (defaults to empty object)
- Returns the rendered HTML string

$3

Parser for the template syntax.

#### Static Methods

##### init()

Create and initialize a parser with all built-in tags.

`text
NodeParser.init(): NodeParser
`

Returns a configured NodeParser instance.

#### Methods

##### registerTagParser(tag)

Register a custom tag parser.

`text
parser.registerTagParser(tag: TagNodeParse): NodeParser
`

- tag - Tag parser definition
- Returns the parser instance for chaining

$3

Utility for loading templates from the file system.

#### Static Properties

##### TEMPLATES_PACKAGE

`text
static readonly TEMPLATES_PACKAGE: string
`

Package identifier for built-in templates: '@ui-doc/html-renderer/templates'

#### Static Methods

##### load(options)

Load templates from a directory.

`text
static async load(options: {
renderer: HtmlRenderer
fileSystem: FileSystem
templatePath: string
}): Promise
`

- options.renderer - The renderer to load templates into
- options.fileSystem - File system instance (typically NodeFileSystem)
- options.templatePath - Path to the templates directory

Error Handling

The renderer throws specific errors for better debugging:

$3

Thrown when a required template is not found.

`ts
try {
renderer.generate(context, 'nonexistent-layout')
} catch (error) {
if (error instanceof HTMLRendererError) {
console.error(Template error: ${error.message})
}
}
`

$3

Thrown when template syntax is invalid.

`ts
import { HTMLRendererSyntaxError } from '@ui-doc/html-renderer'

try {
renderer.addLayout('bad', {
source: 'inline',
content: '{{invalid:syntax',
})
} catch (error) {
if (error instanceof HTMLRendererSyntaxError) {
console.error(Syntax error at line ${error.line}, column ${error.column})
console.error(error.message)
}
}
`

Properties:

- message - Error description
- source - Source identifier
- line - Line number where error occurred
- column - Column number where error occurred
- code - The problematic code snippet

Custom Templates

You can create custom templates to match your design requirements.

$3

`html






{{var:styles}}





{{var:scripts}}



`

$3

`html


- Rollup - Use @ui-doc/rollup
- Vite - Use @ui-doc/vite

These plugins handle template loading, asset copying, and file watching automatically.

TypeScript Support

The package includes full TypeScript definitions. All exported types are available for import:

`ts
import type {
Parser,
RenderContext,
Renderer,
SourceInput,
TagNodeParse,
} from '@ui-doc/html-renderer'
`

Requirements

- Node.js >= 16.0.0
- @ui-doc/core` (peer dependency)

License

See LICENSE.md for license information.