{"id":21310953,"url":"https://github.com/webqit/oohtml-cli","last_synced_at":"2025-10-11T21:36:21.195Z","repository":{"id":38972869,"uuid":"504396321","full_name":"webqit/oohtml-cli","owner":"webqit","description":"A small Command Line utility that automates certain aspects of hand-authored OOHTML-based documents.","archived":false,"fork":false,"pushed_at":"2024-08-02T06:56:52.000Z","size":5547,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-18T11:03:59.908Z","etag":null,"topics":["bundler","html-bundling","html-modules","oohtml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webqit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ox-harri","patreon":null,"open_collective":"webqit","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-06-17T04:44:32.000Z","updated_at":"2024-08-02T06:56:55.000Z","dependencies_parsed_at":"2024-08-02T08:00:45.303Z","dependency_job_id":"3bce89f2-453a-488e-b580-075c9a8128d4","html_url":"https://github.com/webqit/oohtml-cli","commit_stats":{"total_commits":78,"total_committers":2,"mean_commits":39.0,"dds":0.2435897435897436,"last_synced_commit":"9b0d248f6fcf18907b13e7ce15d0297cd8e429a8"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webqit%2Foohtml-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webqit%2Foohtml-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webqit%2Foohtml-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webqit%2Foohtml-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webqit","download_url":"https://codeload.github.com/webqit/oohtml-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225769318,"owners_count":17521258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundler","html-bundling","html-modules","oohtml"],"created_at":"2024-11-21T17:15:19.309Z","updated_at":"2025-10-11T21:36:16.164Z","avatar_url":"https://github.com/webqit.png","language":"JavaScript","funding_links":["https://github.com/sponsors/ox-harri","https://opencollective.com/webqit"],"categories":[],"sub_categories":[],"readme":"# OOHTML Command Line Interface\n\n\u003c!-- BADGES/ --\u003e\n\n\u003cspan class=\"badge-npmversion\"\u003e\u003ca href=\"https://npmjs.org/package/@webqit/oohtml-cli\" title=\"View this project on NPM\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@webqit/oohtml-cli.svg\" alt=\"NPM version\" /\u003e\u003c/a\u003e\u003c/span\u003e\u003cspan class=\"badge-npmdownloads\"\u003e\u003ca href=\"https://npmjs.org/package/@webqit/oohtml-cli\" title=\"View this project on NPM\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/@webqit/oohtml-cli.svg\" alt=\"NPM downloads\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\n\u003c!-- /BADGES --\u003e\n\nOOHTML Command Line is a small utility that automates certain aspects of your hand-authored OOHTML-based documents. You are able to go about coding in absolute free-form with a view to having everything automatically come to shape in one command.\n\n\u003e **Note**\n\u003e \u003cbr\u003eThis is documentation for `OOHTML-CLI@1.x` - for working with [`OOHTML@2.x`](https://github.com/webqit/oohtml/tree/next). (Looking for [`OOHTML-CLI@0.x`](https://github.com/webqit/oohtml-cli/tree/v0.3.4)?)\n\n## Commands\n\n+ [`oohtml bundle`](#command-oohtml-bundle)\n+ [`oohtml config`](#command-oohtml-config)\n\n## Installation\n\nWith [npm available on your terminal](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), run the following command to install OOHTML CLI.\n\n\u003e System Requirements: Node.js 14.0 or later.\n\n```js\nnpm i -g @webqit/oohtml-cli\n```\n\n\u003e The `-g` flag above makes this installation global such that you can directly call `oohtml` from any directory. If you omit it, you may need to prefix each command in this documentation with `npx`; e.g. `npx oohtml bundle`.\n\n## Command: `oohtml bundle`\n\nThe **`oohtml bundle`** command is used to automatically bundle static HTML files from the filesystem into *[HTML Module](http://github.com/webqit/oohtml#html-modules)* elements.\n\n### Overview\n\nHere, you are able to place your `.html` files in a directory, or a hierarchy of directories, and have them automatically come together into an HTML `\u003ctemplate\u003e` element, or an equivalent hierarchy of HTML `\u003ctemplate\u003e` elements - in the case of the latter.\n\nHere's a sample layout of HTML files for an application.\n\n```html\npublic\n  ├── about\n  │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n  ├── home\n  │    └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n  └── index.html \u003c!DOCTYPE html\u003e\n```\n\nThe goal is to translate the above layout into the following *module* structure...\n\n```html\n\u003ctemplate def=\"pages\"\u003e\n\n    \u003ctemplate def=\"home\"\u003e\n       \u003cmain def=\"main.html\" class=\"page-container\"\u003eHome Page\u003c/main\u003e\n    \u003c/template\u003e\n\n    \u003ctemplate def=\"about\"\u003e\n       \u003cmain def=\"main.html\" class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n    \u003c/template\u003e\n\n\u003c/template\u003e\n```\n\n...such that each `\u003cmain\u003e` element can be imported into the `index.html` document using the `\u003cimport\u003e` element:\n\n```html\n\u003c!--\npublic\n ├── index.html\n--\u003e\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eFluffyPets\u003c/title\u003e\n        \u003ctemplate def=\"pages\"\u003e\n\n            \u003ctemplate def=\"home\"\u003e\n                \u003cmain def=\"main.html\" class=\"page-container\"\u003eHome Page\u003c/main\u003e\n            \u003c/template\u003e\n\n            \u003ctemplate def=\"about\"\u003e\n                \u003cmain def=\"main.html\" class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n            \u003c/template\u003e\n\n        \u003c/template\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003ch1 data-id=\"headline\"\u003e\u003c/h1\u003e\n        \u003cimport ref=\"/pages/home#main.html\"\u003e\u003cimport\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThe **`oohtml bundle`** command acheives just that! It scans the current directory for those files and, this time, writes them to a new file named `bundle.html`. The bundle contains just the following content:\n\n```html\n\u003c!--\npublic\n ├── bundle.html\n--\u003e\n\u003ctemplate def=\"home\"\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eHome Page\u003c/main\u003e\n\u003c/template\u003e\n\n\u003ctemplate def=\"about\"\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n\u003c/template\u003e\n```\n\nAnd the `index.html` document is able to link to the bundle as an external resource.\n\n```html\n\u003c!--\npublic\n ├── index.html\n--\u003e\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eFluffyPets\u003c/title\u003e\n        \u003ctemplate def=\"pages\" src=\"/bundle.html\"\u003e\u003c/template\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003ch1 data-id=\"headline\"\u003e\u003c/h1\u003e\n        \u003cimport ref=\"/pages/home#main.html\"\u003e\u003cimport\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n\u003e You can find a working example of [a typical module structure](https://github.com/webqit/oohtml#put-together) right at OOHTML's documentation.\n\nThat said, much of this can be customized using *flags* and other options.\n\n### Flags\n\n#### `--recursive`\n\nThis flag gets the bundler to restart a new bundling process for nested directories that have their own `index.html` file. The default behaviour is to see them as *subroots* and ignore them.\n\n```html\npublic\n  ├── about\n  │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n  ├── home\n  │    └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n  ├── subroot \u003c!-- This would be ignored by default because it has an index.html file --\u003e\n  │    ├── home\n  │    │    └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n  │    └── index.html \u003c!DOCTYPE html\u003e\n  └── index.html \u003c!DOCTYPE html\u003e\n```\n\nWith the `--recursiv` flag, the bundler will now recursively bundle the `subroot` directory above. The *subroot* recieves its own `bundle.html` for its contents, and will be omitted from its parent bundle. This gives us the following final structure:\n\n```html\npublic\n  ├── about\n  │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n  ├── home\n  │    └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n  ├── subroot\n  │    ├── home\n  │    │    └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n  │    ├── bundle.html \u003ctemplate def=\"home\"\u003e...\u003c/template\u003e\n  │    └── index.html \u003c!DOCTYPE html\u003e\n  ├── bundle.html \u003ctemplate def=\"about\"\u003e...\u003c/template\u003e \u003ctemplate def=\"home\"\u003e...\u003c/template\u003e\n  └── index.html \u003c!DOCTYPE html\u003e\n```\n\n#### `--auto-embed=[value]`\n\nThis flag gets the bundler to automatically find the `index.html` document at its entry directory and embed the appropriate `\u003ctemplate def=\"[value]\" src=\"/bundle.html\"\u003e\u003c/template\u003e` element on it.\n\n\u003e Replace `[value]` with and actual module name; e.g. `pages`.\n\n### Other Options\n\nThis utility lets us keep additional configurations to a JSON file, to have a better command-line experience! It expects to locate this file at `./.webqit/oohtml-cli/bundler.json`, relative to its entry directory.\n\n\u003e The `./.webqit/oohtml-cli/bundler.json` file may be edited by hand or from a command line walkthrough using [`oohtml config bundler`](#command-oohtml-config).\n\n```shell\npublic\n  ├── .webqit/oohtml-cli/bundler.json\n```\n\n```json\n{\n    \"entry_dir\": \"./\",\n    \"output_dir\": \"./\",\n    \"filename\": \"./bundle.html\",\n    \"plugins\": [],\n\n    \"module_inherits\": \"\",\n    \"module_extends\": \"\",\n    \"remote_module_loading\": \"eager\",\n    \"remote_module_ssr\": true,\n\n    \"public_base_url\": \"/\",\n    \"max_data_url_size\": 1024,\n    \"ignore_folders_by_prefix\": [\".\"],\n    \"create_outline_file\": false,\n\n    \"module_def_attr\": \"def\",\n    \"fragment_def_attr\": \"def\"\n}\n```\n\nFor advanced layout scenerios, a nested directory may have its own `.webqit/oohtml-cli/bundler.json` config, and the bundler will honour those configurations down that subtree.\n\n```html\npublic\n  ├── .webqit/oohtml-cli/bundler.json\n  ├── about\n  │    ├── deep \u003c!-- New configurations take effect from here --\u003e\n  │    │    ├── .webqit/oohtml-cli/bundler.json\n  │    │    └── main.html \u003cmain class=\"page-container\"\u003eDeep Page\u003c/main\u003e\n  │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n```\n\n#### `[entry_dir]`\n\nThis specifies the entry point into the filesystem. The default value is `./`, relative to its host directory. (An absolute path may also be used.)\n\nThis is good for pointing the bundler to the actual *`views` (or equivalent)* folder when working from the actual project root.\n\n```html\nmy-app\n  ├── .webqit/oohtml-cli/bundler.json\n  ├── views\n  │    └── about\n  │         └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n```\n\n#### `[output_dir]`\n\nThis specifies the output directory for the generated `bundle.html` file. The default value is `./`, relative to its host directory. (An absolute path may also be used.)\n\nThis is good for pointing the bundler to the actual *`public` (or equivalent)* folder when working from the actual project root.\n\n```html\nmy-app\n  ├── .webqit/oohtml-cli/bundler.json\n  ├── views\n  │    └── about\n  │          └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n  └── public\n        └── index.html \u003c!DOCTYPE html\u003e\n```\n\n\u003e Typical layouts have the `./public` (or equivalent) directory for both `[entry_dir]` and `[output_dir]`.\n\n#### `[filename]`\n\nThis specifies the file name of the output bundle. The default value is `./bundle.html`, which is resolved relative to [`[output_dir]`](#output_dir).\n\nWhere the given `.webqit/oohtml-cli/bundler.json` config is for a nested directory, having a non-empty `filename` means that the sub directory is bundled to its own `./bundle.html` file and only *linked* to the parent bundle as an external resource.\n\n```html\npublic\n  ├── .webqit/oohtml-cli/bundler.json\n  ├── about\n  │    ├── deep \u003c!-- New configurations take effect from here --\u003e\n  │    │    ├── .webqit/oohtml-cli/bundler.json\n  │    │    └── main.html \u003cmain class=\"page-container\"\u003eDeep Page\u003c/main\u003e\n  │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n```\n\n```html\n\u003c!--\npublic\n ├── bundle.html\n--\u003e\n\u003ctemplate def=\"about\"\u003e\n    \u003ctemplate def=\"deep\" src=\"/about/deep/bundle.html\"\u003e\u003c/template\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n\u003c/template\u003e\n```\n\n\u003e To add the OOHTML `loading=\"lazy\"` attribute to linked modules, see [`[remote_module_loading]`](#remote_module_loading) below.\n\n#### `[plugins]`\n\nThis specifies an optional list of plugins for the bundling operation. (See [Bundler Plugins](#bundler-plugins).) The default value is an empty array `[]`.\n\nThis is good for extending the capabilities of the bundler to custom-load or transform certain file formats that are not natively provided for.\n\n\u003e On the command line, skip this question where not apply. Or follow the prompt to interactively specify plugins, optionally along with their arguments or flags. Entries are asked recursively.\n\nEach entry has the following structure:\n\n+ **`[name]`** - The path to a function, or the name of an installed npm package, that is designed as an [OOHTML CLI Plugin](#bundler-plugins). (The bundler imports plugins using the ES6 `import()` syntax.)\n\n  To refer to the bundler's [built-in plugins](#built-ins), like the markdown-to-HTML loader ([`md-loader`](#md-loader)), simply add the prefix `default:` to the plugin's bare name. E.g. `default:md-loader`.\n\n+ **`[args]`** - Optional list of parameters (arguments/flags) for a plugin - each in name/value pair.\n\n  \u003e On the command line, skip this question where not apply. Or follow the prompt to interactively specify parameters.  Entries are asked recursively.\n\n  Each entry has the following structure:\n\n  + **`[name]`** - The name of the parameter as required by a plugin. E.g. `flavor` - in the default [`md-loader`](#md-loader).\n  + **`[value]`** - The value of the parameter. E.g. `github` - for the `flavor` parameter above.\n\n#### Advanced Options\n\n#### `[public_base_url]`\n\nThis specifies the public path that maps to [`[output_dir]`](#output_dir) on the filesystem. The default value is `/`. The *`src` (or equivalent)* attribute of any automatically-embedded `\u003ctemplate\u003e` element, plus every asset bundled, will be prefixed with this path.\n\n#### `[max_data_url_size]`\n\nThis specifies at what file size an image, or other assets, should be bundled with inline *[data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs)*. (See [Bundling Assets](#bundling-assets) below.) The default value is `1024`, in bytes. Assets smaller than this size will be bundled with inline *data URL*.\n\nThis is good for having small image files embed their own content instead of having them create additional HTTP requests on the page.\n\n#### `[module_inherits]`\n\nThis specifies a space-separated list of *sibling* module IDs that this module inherits, which when set, creates an `inherits` attribute on the module.\n\n```html\n\u003ctemplate def=\"pages\"\u003e\n\n    \u003cheader def=\"header.html\"\u003e\u003c/header\u003e\n    \u003cfooter def=\"footer.html\"\u003e\u003c/footer\u003e\n\n    \u003ctemplate def=\"home\" inherits=\"header.html footer.html\"\u003e\n        \u003cmain def=\"main.html\"\u003e\u003c/main\u003e\n    \u003c/template\u003e\n\n    \u003ctemplate def=\"about\" inherits=\"header.html footer.html\"\u003e\n        \u003cmain def=\"main.html\"\u003e\u003c/main\u003e\n    \u003c/template\u003e\n\n\u003c/template\u003e\n```\n\n*See [how the `inherits` attribute is treated](https://github.com/webqit/oohtml#inheriting-modules) in OOHTML.*\n\n#### `[module_extends]`\n\nThis specifies a *sibling* module ID that this module extends, which when set, creates an `extends` attribute on the module.\n\n```html\n\u003ctemplate def=\"pages\"\u003e\n\n    \u003ctemplate def=\"common\"\u003e\n        \u003cheader def=\"header.html\"\u003e\u003c/header\u003e\n        \u003cfooter def=\"footer.html\"\u003e\u003c/footer\u003e\n    \u003c/template\u003e\n\n    \u003ctemplate def=\"home\" extends=\"common\"\u003e\n        \u003cmain def=\"main.html\"\u003e\u003c/main\u003e\n    \u003c/template\u003e\n\n    \u003ctemplate def=\"about\" extends=\"common\"\u003e\n        \u003cmain def=\"main.html\"\u003e\u003c/main\u003e\n    \u003c/template\u003e\n\n\u003c/template\u003e\n```\n\n*See [how the `extends` attribute is treated](https://github.com/webqit/oohtml#extending-modules) in OOHTML.*\n\n#### `[remote_module_loading]`\n\nThis controls the loading mode for remote-loading modules - `\u003ctemplate src=\"...\"\u003e\u003c/template\u003e`, which when set to `lazy` adds the `loading=\"lazy\"` attribute. The default value is `eager`.\n\n```html\n\u003ctemplate src=\"/bundle.html\" loading=\"lazy\"\u003e\u003c/template\u003e\n```\n\n\u003e The OOHTML `loading=\"lazy\"` attribute tells a remote-loading module to only load its contents on-demand - on the first attempt to access its contents. (See [how lazy-loading works](https://github.com/webqit/oohtml-ssr#lazy-loading) in OOGTML.)\n\n#### `[remote_module_ssr]`\n\nThis controls the \"SSR\" (Server-Side Rendering) flag for remote-loading modules - `\u003ctemplate src=\"...\"\u003e\u003c/template\u003e`, which when set, adds the `ssr` boolean attribute. The default value is `false`.\n\n```html\n\u003ctemplate ssr src=\"/bundle.html\"\u003e\u003c/template\u003e\n```\n\n\u003e The `ssr` attribute enables resource loading for a given element during Server-Side Rendering. (See [how subresources are treated](https://github.com/webqit/oohtml-ssr#subresource-loading) during Server-Side Rendering.)\n\n#### `[ignore_folders_by_prefix]`\n\nThis specifies a comma-separated list of prefixes for certain types of folders to ignore. Folders with a name that begins with any of the listed prefixes are ingnored. The default value is an array of one prefix: `.`.\n\nThis is good for excluding certain system folders or *dot directories* like `.git`. *Dot directories* are automatically excluded by the default value.\n\n```shell\nmy-app\n  ├── .git\n  ├── public\n```\n\n#### `[create_outline_file]`\n\nThis specifies whether or not to generate a JSON outline of the bundle. The generated file is named after [`[filename]`](#filename); e.g. `./bundle.html.json`. The default value is `false`.\n\n```shell\npublic\n  ├── bundle.html\n  ├── bundle.html.json\n```\n\nThis is good for programmatically traversing the bundle structure. Simply `JSON.parse()` the contents of `./bundle.html.json`.\n\n#### OOHTML-Related Options\n\n#### `[module_def_attr]`\n\nThis controls the \"Module Def\" attribute name `def` for the template element and should generally only be changed to align with custom settings in the [OOHTML meta tag](https://github.com/webqit/oohtml#the-polyfill) of the page where the bundle will be used.\n\n#### `[fragment_def_attr]`\n\nThis controls the \"Fragment Def\" attribute name `def` for the template's fragments and should generally only be changed to align with custom settings in the [OOHTML meta tag](https://github.com/webqit/oohtml#the-polyfill) of the page where the bundle will be used.\n\n### Bundling Assets\n\nWhile HTML files are bundled by reading the file's contents into the bundle, assets, like images, are handled differently. These files are copied from their location in [`[entry_dir]`](#entry_dir) into [`[output_dir]`](#output_dir) when these happen to be two different locations on the filesystem. Copying them to [`[output_dir]`](#output_dir) makes them accessible to HTTP requests. An appropriate HTML element that points to an asset's *public* location is automatically generated as a *module export* in the bundle. This is illustrated below.\n\nWe have an image file at `my-app/views/about`, and we have set [`[entry_dir]`](#entry_dir) to `./views` and [`[output_dir]`](#output_dir) to `./public`.\n\n```html\nmy-app\n  └── views\n      ├── about\n      │    ├── image1.png\n      │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n      └── home\n            └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n```\n\nOn running the **`oohtml bundle`** command, our final directory structure will be...\n\n```html\nmy-app\n  ├── public\n  │   └── about\n  │         └── image1.png\n  └── views\n       ├── about\n       │    ├── image1.png\n       │    └── main.html \u003cmain class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n       └── home\n             └── main.html \u003cmain class=\"page-container\"\u003eHome Page\u003c/main\u003e\n```\n\n...and an `\u003cimg\u003e` element pointing to the *public* location of `image1.png` is added as a *module export* to the bundle.\n\n\n```html\n\u003ctemplate def=\"home\"\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eHome Page\u003c/main\u003e\n\u003c/template\u003e\n\n\u003ctemplate def=\"about\"\u003e\n    \u003cimg def=\"image1.png\" src=\"/about/image1.png\" /\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n\u003c/template\u003e\n```\n\nBut where the file size of that image is smaller than `1024` - [`[max_data_url_size]`](#max_data_url_size), its contents is *inlined* as [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs), and no copying takes place on the filesystem.\n\n```html\n\u003ctemplate def=\"home\"\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eHome Page\u003c/main\u003e\n\u003c/template\u003e\n\n\u003ctemplate def=\"about\"\u003e\n    \u003cimg def=\"image1.png\" src=\"data:image/png,%89PNG%0D%0A=\" /\u003e\n    \u003cmain def=\"main.html\" class=\"page-container\"\u003eAbout Page\u003c/main\u003e\n\u003c/template\u003e\n```\n\nThis way, the browser won't have to load it via a HTTP request. (Cutting down on the number of assets to load should greatly speed up the site's load time.)\n\n### Bundler Plugins\n\nOOHTML CLI plugins are packages that extend the capabilities of the OOHTML Bundler. OOHTML CLI comes with certain plugins built-in, and it also makes it possible to provide custom plugins.\n\n#### Overview\n\nPlugins are functions that are called with each file during the bundling process. Multiple plugins are taken in cascade order where a plugin is responsible for calling the next. This makes for an awesome processing pipeline for each file being bundled.\n\n\u003e This, however, requires thoughtfulness in the order in which these plugins are specified.\n\nBy default, the main OOHTML CLI bundler only handles `.html` files, and images, audio and video files. Then it features built-in plugins that extend the list.\n\n#### Built-Ins\n\n##### `md-loader`\n\nThe `md-loader` plugin is used to load `.md` (markdown) files into HTML exports, just the way regular HTML files are. It takes an initial step of converting the markdown content into HTML using the [Showdown](https://github.com/showdownjs/showdown) library, then goes ahead to add it to the bundle as a *module export*. Markdown links are automatically resolved to better work as HTML links. And a few other transformations are supported through arguments/flags. (Learn more about specifying arguments/flags for a plugin [here](#plugins).)\n\n###### Arguments/Flags\n\nAll parameters are optional.\n\n+ **`outline_generation`** - Set this to a *non-empty* value to generate a JSON outline of the page's content. The generated outline will show up in the meta data for the file in the bundle's overall [JSON outline](#create_outline_file).\n+ **`code_highlighting`** - Set this to a *non-empty* value to transform code blocks into stylable markup using the [Showdown-Highlight](https://github.com/Bloggify/showdown-highlight) utility. The transformed code blocks are highlighted in the UI on adding any of the [Highlight.js](https://highlightjs.org/) CSS to the page.\n+ **`flavor`** - This equates to any of [Showdown's three flavours](https://github.com/showdownjs/showdown#flavors): `original`, `vanilla`, `github`.\n\n###### Other\n\n+ **Markdown Metadata** - By default, `md-loader` automatically parses any found markdown metadata (defined at the top of the document between ««« and »»» or between --- and ---) into JSON. This metadata object is added as a node to the bundle's overall [JSON outline](#create_outline_file). Below is an example metadata:\n\n  ```md\n  ---\n  description: Page description.\n  ---\n  # Page Title\n  ```\n+ **Markdown Tables** - The markdown table syntax is supported by default. Below is an example table:\n\n  ```md\n  | h1    |    h2   |      h3 |\n  |:------|:-------:|--------:|\n  | 100   | [a][1]  | ![b][2] |\n  | *foo* | **bar** | ~~baz~~ |\n  ```\n\n###### Usage\n\nThe `md-loader` plugin is used by specifying `default:md-loader` in the [`[plugins]`](#plugins) config option.\n\n#### Custom Plugins\n\nCustom Plugins are basic JavaScript modules that *export* a `type` variable (`export const type;`), and a function named `handle` (`export function handle() {}`). The `type` variable is the plugin type, and this should be either `input` or `output`.\n\n###### Input Plugins\n\n*Input* plugins are plugins that are called to load a resource and return its contents.\n\n```js\nexport const type = 'input';\nexport function handle( event, args, recieved, next ) {\n    if ( received || !event.resource.endsWith( '.css' ) ) {\n        // Or let the flow continue\n        return next( received );\n    }\n    console.log( event.resource ); // File name\n    console.log( args );\n    return {\n        type: 'text/css'\n        contents: '...',\n    };\n}\n```\n\n**Parameters**\n\n+ **`event.resource: String`** - The filename of the resource being processed.\n+ **`event.params: Object`** - The [`options` object](#other-options) that the Bundler was initialized with.\n+ **`event.indentation: Number`** - A number which represents how deep in the source directory the given resource is. This number is `0` at the root of the source directory.\n+ **`args: Object`** - The [`args` object](#plugins) defined specifically for the plugin.\n+ **`received: Object`** - The output forwarded (that is, `next()`ed) from the previous plugin in the pipeline, if any.\n+ **`next: Function`** - A function that forwards control to the next plugin in the pipeline, if any, and if none, to the default internal *loader*. The `next()` accpets only one parameter, which is received by the next plugin on its `received` parameter.\n\n**Return Schema**\n\n+ **`type: String`** - The MIME type of the resource.\n+ **`contents: String`** - The contents of the resource.\n\n###### Output Plugins\n\n*Output* plugins are plugins that are called to transform a loaded resource into its final HTML representation.\n\n```js\nexport const type = 'output';\nexport function handle( event, args, recieved, next ) {\n    if ( received || event.resource.type !== 'text/css' ) {\n        // Or let the flow continue\n        return next( received );\n    }\n    console.log( event.resource.type ); // text/css\n    console.log( event.resource.contents ); // ...\n    console.log( args );\n    return {\n        html: '\u003cstyle rel=\"stylesheet\"\u003e...\u003c/style\u003e'\n        json: {},\n    };\n}\n```\n\n**Parameters**\n\n+ **`event.resource: Object`** - The object that represents a loaded resource - as returned by a *loader*.\n+ **`event.params: Object`** - The [`options` object](#other-options) that the Bundler was initialized with.\n+ **`event.indentation: Number`** - A number which represents how deep in the source directory the given resource is. This number is `0` at the root of the source directory.\n+ **`args: Object`** - The [`args` object](#plugins) defined specifically for the plugin.\n+ **`received: Object`** - The output forwarded (that is, `next()`ed) from the previous plugin in the pipeline, if any.\n+ **`next: Function`** - A function that forwards control to the next plugin in the pipeline, if any, and if none, to the default internal *loader*. The `next()` accpets only one parameter, which is received by the next plugin on its `received` parameter.\n\n**Return Schema**\n\n+ **`html: String`** - The HTML representation of the resource.\n+ **`json: Object`** - An optional object that contains metadata about the resource. (This metadata object is added as a node to the overall [JSON outline](#create_outline_file) generated by the bundler.)\n\n###### Usage\n\nCustom plugins are used by specifying their filename in the [`[plugins]`](#plugins) config option. Plugins installed as an npm package are used by specifying their package name.\n\n## Getting Involved\n\nAll forms of contributions and PR are welcome! To report bugs or request features, please submit an [issue](https://github.com/webqit/oohtml-cli/issues). For general discussions, ideation or community help, please join our github [Discussions](https://github.com/webqit/oohtml-cli/discussions).\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebqit%2Foohtml-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebqit%2Foohtml-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebqit%2Foohtml-cli/lists"}