{{var:title}}
{{if:description}}
{{/if}}
{{if:sections}}
{{for:sections}}
{{partial:custom-section}}
{{/for}}
{{/if}}
HTML renderer for UI-Doc.
npm install @ui-doc/html-rendererHTML 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.
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
``bash`
npm install @ui-doc/html-renderer @ui-doc/core
`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:
,
})renderer.addPage('default', {
source: 'inline',
content:
,
})// Generate HTML from context
const html = renderer.generate({
title: 'My Documentation',
page: {
title: 'Welcome',
content: '
Documentation content here
',
},
assets: [],
})
`$3
`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}}
{{var:description}}
{{var:page.content}}
{{var:userInput escape}}
`$3
Render content conditionally:
`html
{{if:showContent}}
This is visible when showContent is truthy
{{/if}}
`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)
`#### Object Loops
`html
{{for:colors}}
- {{var:_loop.key}}: {{var:_loop.value}}
{{/for}}
- red: #f00
- green: #0f0
- blue: #00f
`#### Looping Over Object Arrays
`html
{{for:sections}}
{{var:title}}
{{var:content}}
{{/for}}
`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: ,
})
`$3
Define page-specific content structures:
`ts
renderer.addPage('default', {
source: 'my-page.html',
content: {{var:description}}
,
})
`$3
Create reusable template components:
`ts
renderer.addPartial('section', {
source: 'section.html',
content: ,
})
`Loading Templates
$3
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
@ui-doc/html-renderer/ui-doc.cssMinified CSS
@ui-doc/html-renderer/ui-doc.min.css
`$3
`bash
Full JavaScript
@ui-doc/html-renderer/ui-doc.jsMinified JavaScript (for use in browsers)
@ui-doc/html-renderer/ui-doc.min.js
`$3
`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 stringThe
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 directoryError 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 snippetCustom Templates
You can create custom templates to match your design requirements.
$3
`html
{{var:title}}
{{var:styles}}
{{page:page.id page}}
{{var:scripts}}
`$3
`html
{{var:title}}
{{if:description}}
{{var:description}}
{{/if}}
{{if:sections}}
{{for:sections}}
{{partial:custom-section}}
{{/for}}
{{/if}}
`Integration with Build Tools
While you can use the HTML renderer directly, it's typically used through build tool plugins:
@ui-doc/rollup
- Vite - Use @ui-doc/viteThese 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)See LICENSE.md for license information.