# 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 '' - 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 `$include`s.
### In JS
```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 `` and fragments with `
`. 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
```
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
```html
ROGUELIKE
```
### content.stage
```recital
$include './head.html'
= Put content in here!
#
This is the first scene.
#
This is the second scene.
$include './footer.html'
```
### footer.html
```html