recital / exporters / html
README.md

Stage Export to HTML

Converts a Recital .stage file into an HTML page, suitable for then converting into pdf or other form. Uses markdown to process non-Recital markup, which generally follows the CommonMark spec.

Usage

CLI

stage-html input-file.stage optional-file-2.stage -o outputfile.html

	Options:
		*TAG OPTIONS*
		--sceneTag tagName - Tag (without brackets) that wraps around scenes. Defaults to 'section'
		--blockTag tagName - Tag (without brackets) that wraps around fragments. Defaults to 'div'
		--separator '<hr />' - HTML that goes between scenes. Defaults to nothing.

		*CONVERSION OPTIONS*
		--useIncludes - if set, will accept the $include command to have HTML templates. Defaults to false.
		--pureMarkdown - if set, will not use any of the common extensions (e.g. wikilinks). Defaults to false.

If you have multiple input files, they'll be concatenated. Prefer using the $include command with the --useIncludes flag instead and just pointing to the first file; the parser supports $includes.

In JS

const stageToHtml = require('@a-morphous/recital-stage-html')

const defaultOpts = {
	sceneTag: 'section',
	blockTag: 'div',
	sceneSeparator: '',
}

return stageToHTML(fs.readFileSync('input-file.stage', 'utf-8'), defaultOpts)

How does it work?

By default, the parser wraps scenes with <section> and fragments with <div>. The only other metadata that is relevant is the default id and classes metadata tags, which are set as the id and class of the resulting HTML element, respectively. The parser enforces an id; if a scene or a fragment is defined without one, one will be automatically generated.

All inline markup is parsed with micromark in Markdown, essentially turning the original Recital document into a Markdown superscript.

You can also add a separator between every scene, which is defined in the --separator option. This separator is added as-is as an HTML string with no further processing.

If the --useIncludes flag is set, the logic tag $include will also operate, defined in the common extensions.:

The include command's usage is:

$include <file to include> <raw: boolean>

The file to include should be a relative path from the original parsed file, or an absolute path.

'raw' determines whether we process the included stage file for more includes, or just leave the text unprocessed.

Limitations

This parser ultimately converts to a string, and does not check the validity of the generated HTML. It also doesn't set proper head tags, with the assumption that additional processing be used to create a whole page.

In addition, there is no functionality to add script tags or any kind of Javascript from within the parser.

Recipes

To use this as a full-blown HTML generator, you can take advantage of the --useIncludes flag, and include things like CSS styles and JS scripts via external includes.

Something like:

head.html

<!DOCTYPE html>
<html>
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width,initial-scale=1" />
		<title>ROGUELIKE</title>
		<link rel="stylesheet" href="css/skeleton.css" />
	</head>
	<body></body>
</html>

content.stage

$include './head.html'

= Put content in here!
#

This is the first scene.

#

This is the second scene.

$include './footer.html'

footer.html

	</body>
</html>
Powered by GitFront