{"_id":"@a-morphous/recital-stage-html","name":"@a-morphous/recital-stage-html","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.1":{"name":"@a-morphous/recital-stage-html","version":"1.1.1","description":"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.","main":"dist/stage-html.js","module":"dist/stage-html.module.js","bin":{"stage-html":"dist/cli.js"},"repository":{"type":"git","url":"git+https://github.com/a-morphous/recital.git"},"author":{"name":"Amorphous"},"license":"MPL 2.0","dependencies":{"@a-morphous/recital":"^1.1.0","@a-morphous/recital-ext-common-commands":"^1.1.0","micromark":"^3.0.10","minimist":"^1.2.6","smartypants":"^0.1.6"},"devDependencies":{"esbuild":"^0.14.34","@a-morphous/test":"^1.0.0"},"scripts":{"test":"test test/*.js","build":"node build","dryRun":"pnpm publish --dry-run","pub":"pnpm publish --access public"},"bugs":{"url":"https://github.com/a-morphous/recital/issues"},"homepage":"https://github.com/a-morphous/recital#readme","_id":"@a-morphous/recital-stage-html@1.1.1","_integrity":"sha512-l+j8VxBdLKYDFErldhdUe9DBBWMEHBDxBJiFZfniTiASZw1ph8UAa17gKTmI4PBfZ/yxlk8w6TZ5hG1ci+iLQQ==","_resolved":"/private/var/folders/pd/2r2pf8ln2cv61g2b_k9fr5nc0000gn/T/03c439b88c7cef0c6786a1e1bab721d8/a-morphous-recital-stage-html-1.1.1.tgz","_from":"file:a-morphous-recital-stage-html-1.1.1.tgz","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-l+j8VxBdLKYDFErldhdUe9DBBWMEHBDxBJiFZfniTiASZw1ph8UAa17gKTmI4PBfZ/yxlk8w6TZ5hG1ci+iLQQ==","shasum":"1c58cd1ed76dea0b1e0645d46573040a46d65452","tarball":"https://registry.npmjs.org/@a-morphous/recital-stage-html/-/recital-stage-html-1.1.1.tgz","fileCount":7,"unpackedSize":679713,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIBYXfZM9l/5h30QXm84ghHaEepwgtLNmQNX2aT8F3rgCAiEApO04CpXn/ptLqXPv9q8jceYBPJTt1YBkeJb0xXkzNzY="}]},"_npmUser":{"name":"amorphous","email":"84998015+a-morphous@users.noreply.github.com"},"directories":{},"maintainers":[{"name":"amorphous","email":"84998015+a-morphous@users.noreply.github.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/recital-stage-html_1.1.1_1729321184064_0.28721571273276747"},"_hasShrinkwrap":false}},"time":{"created":"2024-10-19T06:59:43.950Z","1.1.1":"2024-10-19T06:59:44.250Z","modified":"2024-10-19T06:59:44.559Z"},"maintainers":[{"name":"amorphous","email":"84998015+a-morphous@users.noreply.github.com"}],"description":"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.","homepage":"https://github.com/a-morphous/recital#readme","repository":{"type":"git","url":"git+https://github.com/a-morphous/recital.git"},"author":{"name":"Amorphous"},"bugs":{"url":"https://github.com/a-morphous/recital/issues"},"license":"MPL 2.0","readme":"# Stage Export to HTML\n\nConverts 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.\n\n## Usage\n\n### CLI\n\n```\nstage-html input-file.stage optional-file-2.stage -o outputfile.html\n\n\tOptions:\n\t\t*TAG OPTIONS*\n\t\t--sceneTag tagName - Tag (without brackets) that wraps around scenes. Defaults to 'section'\n\t\t--blockTag tagName - Tag (without brackets) that wraps around fragments. Defaults to 'div'\n\t\t--separator '<hr />' - HTML that goes between scenes. Defaults to nothing.\n\n\t\t*CONVERSION OPTIONS*\n\t\t--useIncludes - if set, will accept the $include command to have HTML templates. Defaults to false.\n\t\t--pureMarkdown - if set, will not use any of the common extensions (e.g. wikilinks). Defaults to false.\n```\n\nIf 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.\n\n### In JS\n\n```js\nconst stageToHtml = require('@a-morphous/recital-stage-html')\n\nconst defaultOpts = {\n\tsceneTag: 'section',\n\tblockTag: 'div',\n\tsceneSeparator: '',\n}\n\nreturn stageToHTML(fs.readFileSync('input-file.stage', 'utf-8'), defaultOpts)\n```\n\n## How does it work?\n\nBy 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.\n\nAll inline markup is parsed with `micromark` in Markdown, essentially turning the original Recital document into a Markdown superscript.\n\nYou 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.\n\nIf the `--useIncludes` flag is set, the logic tag `$include` will also operate, defined in the common extensions.:\n\nThe include command's usage is:\n\n```\n$include <file to include> <raw: boolean>\n```\n\nThe file to include should be a relative path from the original parsed file, or an absolute path.\n\n'raw' determines whether we process the included stage file for more includes, or just leave the text unprocessed.\n\n## Limitations\n\nThis 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.\n\nIn addition, there is no functionality to add script tags or any kind of Javascript from within the parser.\n\n## Recipes\n\nTo 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.\n\nSomething like:\n\n### head.html\n\n```html\n<!DOCTYPE html>\n<html>\n\t<head>\n\t\t<meta charset=\"UTF-8\" />\n\t\t<meta name=\"viewport\" content=\"width=device-width,initial-scale=1\" />\n\t\t<title>ROGUELIKE</title>\n\t\t<link rel=\"stylesheet\" href=\"css/skeleton.css\" />\n\t</head>\n\t<body></body>\n</html>\n```\n\n### content.stage\n\n```recital\n$include './head.html'\n\n= Put content in here!\n#\n\nThis is the first scene.\n\n#\n\nThis is the second scene.\n\n$include './footer.html'\n```\n\n### footer.html\n\n```html\n\t</body>\n</html>\n```\n","readmeFilename":"README.md"}