chore(release): 1.5.0-develop.2 [skip ci]

## [1.5.0-develop.2](https://github.com/chenasraf/simple-scaffold/compare/v1.5.0-develop.1...v1.5.0-develop.2) (2023-05-03)

### Bug Fixes

* move dependency to dev dependency ([408a940](408a940853))

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## [1.5.0-develop.2](https://github.com/chenasraf/simple-scaffold/compare/v1.5.0-develop.1...v1.5.0-develop.2) (2023-05-03)
+
+
+### Bug Fixes
+
+* move dependency to dev dependency ([408a940](https://github.com/chenasraf/simple-scaffold/commit/408a94085366bb4e39391fcfcfa7df78b06a480f))
+
 ## [1.5.0-develop.1](https://github.com/chenasraf/simple-scaffold/compare/v1.4.0...v1.5.0-develop.1) (2023-05-02)
 
 

README.md

@@ -3,7 +3,7 @@
 <h2 align="center">
 
 [GitHub](https://github.com/chenasraf/simple-scaffold) |
-[Documentation](https://casraf.dev/simple-scaffold) |
+[Documentation](https://chenasraf.github.io/simple-scaffold) |
 [NPM](https://npmjs.com/package/simple-scaffold) | [casraf.dev](https://casraf.dev)
 
 ![version](https://img.shields.io/github/package-json/v/chenasraf/simple-scaffold/master?label=version)

package.json

@@ -2,7 +2,7 @@
   "name": "simple-scaffold",
   "version": "1.5.0",
   "description": "A simple command to generate any file structure, from single components to entire app boilerplates.",
-  "homepage": "https://casraf.dev/simple-scaffold",
+  "homepage": "https://chenasraf.github.io/simple-scaffold",
   "repository": "https://github.com/chenasraf/simple-scaffold.git",
   "author": "Chen Asraf <inbox@casraf.com>",
   "license": "MIT",
@@ -40,7 +40,6 @@
     "handlebars": "^4.7.7",
     "lodash": "^4.17.21",
     "massarg": "^1.0.7-pre.1",
-    "semantic-release-conventional-commits": "^3.0.0",
     "util.promisify": "^1.1.1"
   },
   "devDependencies": {
@@ -59,6 +58,7 @@
     "mock-fs": "^5.2.0",
     "rimraf": "^5.0.0",
     "semantic-release": "^21.0.1",
+    "semantic-release-conventional-commits": "^3.0.0",
     "ts-jest": "^29.1.0",
     "ts-node": "^10.9.1",
     "typedoc": "^0.24.6",

pages/cli.md

@@ -1,158 +1,73 @@
 ## Available flags
 
-The following is the help text from the `simple-scaffold` binary. To see this and more information
-anytime, add the `-h` or `--help` flag to your call, e.g. `npx simple-scaffold@latest -h`.
-
 ```text
 Usage: simple-scaffold [options]
-
-Create structured files based on templates.
-
-Options:
-
-  --help|-h                       Display help information
-
-  --name|-n                       Name to be passed to the generated files. {{name}} and
-                                  {{Name}} inside contents and file names will be replaced
-                                  accordingly.
-
-  --config|-c                     Filename or https git URL to load config from instead of
-                                  passing arguments to CLI or using a Node.js script. You may
-                                  pass a JSON or JS file with a relative or absolute
-                                  path
-
-  --github|-gh                    GitHub path to load config from instead of passing
-                                  arguments to CLI or using a Node.js script. You may pass a
-                                  GitHub path (e.g. username/package#scaffold.config.js). You
-                                  may also optionally add a key (same as passing --key) to load
-                                  from inside the config.
-
-  --key|-k                        Key to load inside the config file. This overwrites the
-                                  config key provided after the colon in --config (e.g. --config
-                                  scaffold.cmd.js:component)
-
-  --output|-o                     Path to output to. If --create-sub-folder is enabled,
-                                  the subfolder will be created inside this path.
-                                  (default: current dir)
-
-  --templates|-t                  Template files to use as input. You may provide multiple
-                                  files, each of which can be a relative or absolute path, or a
-                                  glob pattern for multiple file matching easily.
-
-  --overwrite|-w                  Enable to override output files, even if they already
-                                  exist. (default: false)
-
-  --data|-d                       Add custom data to the templates. By default, only your
-                                  app name is included.
-
-  --append-data|-D                Append additional custom data to the templates, which
-                                  will overwrite --data, using an alternate syntax, which is
-                                  easier to use with CLI: -D key1=string -D key2:=raw
-
-  --create-sub-folder|-s          Create subfolder with the input name
-                                  (default: false)
-
-  --sub-folder-name-helper|-sh    Default helper to apply to subfolder name when using
-                                  `--create-sub-folder true`.
-
-  --quiet|-q                      Suppress output logs (Same as --verbose 0)
-                                  (default: false)
-
-  --verbose|-v                    Determine amount of logs to display. The values are:
-                                  0 (none) | 1 (debug) | 2 (info) | 3 (warn) | 4
-                                  (error). The provided level will display messages of
-                                  the same level or higher. (default:
-                                  2)
-
-  --dry-run|-dr                   Don't emit files. This is good for testing your
-                                  scaffolds and making sure they don't fail, without having to
-                                  write actual file contents or create directories.
-                                  (default: false)
-
-Version:  1.4.0
-Copyright © Chen Asraf 2017-2023
-
-Documentation: https://casraf.dev/simple-scaffold
-NPM: https://npmjs.com/package/simple-scaffold
-GitHub: https://github.com/chenasraf/simple-scaffold
-
-✨  Done in 11.00s.
-❯ yarn build-cmd -h
-yarn run v1.22.19
-$ yarn build && yarn cmd -h
-$ yarn clean && tsc && chmod -R +x ./dist && cp ./package.json ./README.md ./dist/
-$ rimraf dist/
-$ node --trace-warnings dist/cmd.js -h
-Usage: simple-scaffold [options]
-
-Create structured files based on templates.
-
-Options:
-
-  --help|-h                       Display help information
-
-  --name|-n                       Name to be passed to the generated files. {{name}} and
-                                  {{Name}} inside contents and file names will be replaced
-                                  accordingly.
-
-  --config|-c                     Filename or https git URL to load config from instead of
-                                  passing arguments to CLI or using a Node.js script. You may
-                                  pass a JSON or JS file with a relative or absolute path, or a
-                                  fully qualified git repository URL.
-
-  --github|-gh                    GitHub path to load config from instead of passing
-                                  arguments to CLI or using a Node.js script. You may pass a
-                                  GitHub path (e.g. username/package#scaffold.config.js). You
-                                  may also optionally add a key (same as passing --key) to load
-                                  from inside the config.
-
-  --key|-k                        Key to load inside the config file. This overwrites the
-                                  config key provided after the colon in --config (e.g. --config
-                                  scaffold.cmd.js:component)
-
-  --output|-o                     Path to output to. If --create-sub-folder is enabled,
-                                  the subfolder will be created inside this path.
-                                  (default: current dir)
-
-  --templates|-t                  Template files to use as input. You may provide multiple
-                                  files, each of which can be a relative or absolute path, or a
-                                  glob pattern for multiple file matching easily.
-
-  --overwrite|-w                  Enable to override output files, even if they already
-                                  exist. (default: false)
-
-  --data|-d                       Add custom data to the templates. By default, only your
-                                  app name is included.
-
-  --append-data|-D                Append additional custom data to the templates, which
-                                  will overwrite --data, using an alternate syntax, which is
-                                  easier to use with CLI: -D key1=string -D key2:=raw
-
-  --create-sub-folder|-s          Create subfolder with the input name
-                                  (default: false)
-
-  --sub-folder-name-helper|-sh    Default helper to apply to subfolder name when using
-                                  `--create-sub-folder true`.
-
-  --quiet|-q                      Suppress output logs (Same as --verbose 0)
-                                  (default: false)
-
-  --verbose|-v                    Determine amount of logs to display. The values are:
-                                  0 (none) | 1 (debug) | 2 (info) | 3 (warn) | 4
-                                  (error). The provided level will display messages of
-                                  the same level or higher. (default:
-                                  2)
-
-  --dry-run|-dr                   Don't emit files. This is good for testing your
-                                  scaffolds and making sure they don't fail, without having to
-                                  write actual file contents or create directories.
-                                  (default: false)
 ```
 
+To see this and more information anytime, add the `-h` or `--help` flag to your call, e.g.
+`npx simple-scaffold@latest -h`.
+
+| Command \| alias                  |                                                                                                                                                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--help`\|`-h`                    | Display help information                                                                                                                                                                            |
+| `--name`\|`-n`                    | Name to be passed to the generated files. {{name}} and {{Name}} inside contents and file names will be replaced accordingly.                                                                        |
+| `--config`\|`-c`                  | Filename or HTTPS git URL to load config from instead of passing arguments to CLI or using a Node.js script.                                                                                        |
+| `--github`\|`-gh`                 | GitHub path to load config from instead of passing arguments to CLI or using a Node.js script.                                                                                                      |
+| `--key`\|`-k`                     | Key to load inside the config file. This overwrites the config key provided after the colon in --config (e.g. --config scaffold.cmd.js:component)                                                   |
+| `--output`\|`-o`                  | Path to output to. If --create-sub-folder is enabled, the subfolder will be created inside this path. (default: current dir)                                                                        |
+| `--templates`\|`-t`               | Template files to use as input. You may provide multiple files, each of which can be a relative or absolute path, or a glob pattern for multiple file matching easily.                              |
+| `--overwrite`\|`-w`               | Enable to override output files, even if they already exist. (default: false)                                                                                                                       |
+| `--data`\|`-d`                    | Add custom data to the templates. By default, only your app name is included.                                                                                                                       |
+| `--append-data`\|`-D`             | Append additional custom data to the templates, which will overwrite --data, using an alternate syntax, which is easier to use with CLI: -D key1=string -D key2:=raw                                |
+| `--create-sub-folder`\|`-s`       | Create subfolder with the input name (default: false)                                                                                                                                               |
+| `--sub-folder-name-helper`\|`-sh` | Default helper to apply to subfolder name when using `--create-sub-folder true`.                                                                                                                    |
+| `--quiet`\|`-q`                   | Suppress output logs (Same as --verbose 0) (default: false)                                                                                                                                         |
+| `--verbose`\|`-v`                 | Determine amount of logs to display. The values are: 0 (none) \| 1 (debug) \| 2 (info) \| 3 (warn) \| 4 (error). The provided level will display messages of the same level or higher. (default: 2) |
+| `--dry-run`\|`-dr`                | Don't emit files. This is good for testing your scaffolds and making sure they don't fail, without having to write actual file contents or create directories. (default: false)                     |
+
+## Examples:
+
 > See
-> [Configuration Files](https://chenasraf.githun.io/simple-scaffold/pages/docs/configuration_files.md)
+> [Configuration Files](https://chenasraf.github.io/simple-scaffold/pages/docs/configuration_files.md)
 > for organizing multiple scaffold types into easy-to-maintain files
 
+Usage with config file
+
+```shell
+$ simple-scaffold -c scaffold.cmd.js --key component
+```
+
+Usage with GitHub config file
+
+```shell
+$ simple-scaffold -gh chenasraf/simple-scaffold --key component
+```
+
+Usage with https git URL (for non-GitHub)
+
+```shell
+$ simple-scaffold -c \
+      https://example.com/user/template.git#scaffold.cmd.js --key component
+```
+
+Full syntax with config path and template key (applicable to all above methods)
+
+```shell
+$ simple-scaffold -c scaffold.cmd.js:component MyComponent
+```
+
+Excluded template key, assumes 'default' key
+
+```shell
+$ simple-scaffold -c scaffold.cmd.js MyComponent
+```
+
+Shortest syntax for GitHub, assumes file 'scaffold.cmd.js' and template key 'default'
+
+```shell
+$ simple-scaffold -gh chenasraf/simple-scaffold MyComponent
+```
+
 You can also add this as a script in your `package.json`:
 
 ```json

src/cmd.ts

@@ -29,13 +29,13 @@ export async function parseCliArgs(args = process.argv.slice(2)) {
         name: "config",
         aliases: ["c"],
         description:
-          "Filename or https git URL to load config from instead of passing arguments to CLI or using a Node.js script. You may pass a JSON or JS file with a relative or absolute path, or a fully qualified git repository URL.",
+          "Filename or https git URL to load config from instead of passing arguments to CLI or using a Node.js script. See examples for syntax.",
       })
       .option({
         name: "github",
         aliases: ["gh"],
         description:
-          "GitHub path to load config from instead of passing arguments to CLI or using a Node.js script. You may pass a GitHub path (e.g. username/package#scaffold.config.js). You may also optionally add a key (same as passing --key) to load from inside the config.",
+          "GitHub path to load config from instead of passing arguments to CLI or using a Node.js script. See examples for syntax.",
       })
       .option({
         name: "key",
@@ -121,16 +121,41 @@ export async function parseCliArgs(args = process.argv.slice(2)) {
       //   description: "Usage",
       //   output: "",
       // })
+      .example({
+        description: "Usage with config file",
+        input: "simple-scaffold -c scaffold.cmd.js --key component",
+      })
+      .example({
+        description: "Usage with GitHub config file",
+        input: "simple-scaffold -gh chenasraf/simple-scaffold --key component",
+      })
+      .example({
+        description: "Usage with https git URL (for non-GitHub)",
+        input: "simple-scaffold -c https://example.com/user/template.git#scaffold.cmd.js --key component",
+      })
+      .example({
+        description: "Full syntax with config path and template key (applicable to all above methods)",
+        input: "simple-scaffold -c scaffold.cmd.js:component MyComponent",
+      })
+      .example({
+        description: "Excluded template key, assumes 'default' key",
+        input: "simple-scaffold -c scaffold.cmd.js MyComponent",
+      })
+      .example({
+        description: "Shortest syntax for GitHub, assumes file 'scaffold.cmd.js' and template key 'default'",
+        input: "simple-scaffold -gh chenasraf/simple-scaffold MyComponent",
+      })
       .help({
         binName: "simple-scaffold",
         useGlobalColumns: true,
         usageExample: "[options]",
+        printWidth: 100,
         header: [`Create structured files based on templates.`].join("\n"),
         footer: [
           `Version:  ${pkg.version}`,
           `Copyright © Chen Asraf 2017-${new Date().getFullYear()}`,
           ``,
-          `Documentation: ${chalk.underline`https://casraf.dev/simple-scaffold`}`,
+          `Documentation: ${chalk.underline`https://chenasraf.github.io/simple-scaffold`}`,
           `NPM: ${chalk.underline`https://npmjs.com/package/simple-scaffold`}`,
           `GitHub: ${chalk.underline`https://github.com/chenasraf/simple-scaffold`}`,
         ].join("\n"),

src/types.ts

@@ -3,7 +3,8 @@ import { HelperDelegate } from "handlebars/runtime"
 /**
  * The config object for defining a scaffolding group.
  *
- * @see https://github.com/chenasraf/simple-scaffold#readme
+ * @see {@link https://chenasraf.github.io/simple-scaffold/pages/node.html | Node.js usage}
+ * @see {@link https://chenasraf.github.io/simple-scaffold/pages/cli.html | CLI usage}
  * @see {@link DefaultHelpers}
  * @see {@link CaseHelpers}
  * @see {@link DateHelpers}
@@ -131,10 +132,8 @@ export interface ScaffoldConfig {
    * @see {@link DefaultHelpers}
    * @see {@link CaseHelpers}
    * @see {@link DateHelpers}
-   * @see https://casraf.dev/simple-scaffold#helpers
+   * @see {@link https://chenasraf.github.io/simple-scaffold/pages/templates.html | Templates}
-   * @see https://casraf.dev/simple-scaffold#built-in-helpers
+   * */
-   * @see https://handlebarsjs.com/guide/#custom-helpers
-   */
   helpers?: Record<string, Helper>
 
   /**
@@ -341,4 +340,15 @@ export interface ScaffoldCmdConfig {
   github?: string
 }
 
+/**
+ * A mapping of scaffold template keys to their configurations.
+ *
+ * Each configuration is a {@link ScaffoldConfig} object.
+ *
+ * The key is the name of the template, and the value is the configuration for that template.
+ *
+ * When no template key is provided to the scaffold command, the "default" template is used.
+ *
+ * @see {@link ScaffoldConfig}
+ */
 export type ScaffoldConfigFile = Record<string, ScaffoldConfig>