diff --git a/README.md b/README.md index bfc88dd..99d4cdb 100644 --- a/README.md +++ b/README.md @@ -31,54 +31,76 @@ lifting for you and start building your projects faster and more efficiently tod --- -## Quick Start +## Documentation -### Local Templates +See full documentation [here](https://chenasraf.github.io/simple-scaffold). -The fastest way to get started is to use `npx` to immediately start a scaffold process. +- [Command Line Interface (CLI) usage](https://chenasraf.github.io/simple-scaffold/docs/usage/cli) +- [Node.js usage](https://chenasraf.github.io/simple-scaffold/docs/usage/node) +- [Templates](https://chenasraf.github.io/simple-scaffold/docs/usage/templates) +- [Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files) +- [Migration](https://chenasraf.github.io/simple-scaffold/docs/usage/migration) -Prepare any templates you want to use - for example, in the directory `templates/component`; and use -that in the CLI args. Here is a simple example file: +## Getting Started -Simple Scaffold will maintain any file and directory structure you try to generate. +### Cheat Sheet -`templates/component/{{ pascalName name }}.tsx` +A quick rundown of common usage scenarios: -```tsx -// Created: {{ now 'yyyy-MM-dd' }} -import React from 'react' +- Remote template config file on GitHub: -export default {{pascalCase name}}: React.FC = (props) => { - return ( -
{{pascalCase name}} Component
- ) -} -``` + ```sh + npx simple-scaffold -g username/repository -c scaffold.js -k component NewComponentName + ``` -To generate the template output, run: +- Local template config file: + + ```sh + npx simple-scaffold -c scaffold.js -k component NewComponentName + ``` + +- Local one-time usage: + + ```sh + npx simple-scaffold -t templates/component -o src/components NewComponentName + ``` + +### Remote Configurations + +The fastest way to get started is to is to re-use someone else's (or your own) work using a template +repository. + +A remote config can be loaded in one of these ways: + +- For templates hosted on GitHub, the syntax is `-g user/repository_name` +- For other Git platforms like GitLab, use `-g https://example.com/user/repository_name.git` + +These remote configurations support multiple scaffold groups, which can be specified using the +`--key` or `-k` argument: ```sh -# generate single component -$ npx simple-scaffold@latest \ - -t templates/component -o src/components PageWrapper +$ npx simple-scaffold \ + -g chenasraf/simple-scaffold \ + -k component \ + PageWrapper + +# equivalent to: +$ npx simple-scaffold \ + -g https://github.com/chenasraf/simple-scaffold.git \ + -c scaffold.config.js \ + -k component \ + PageWrapper ``` -This will immediately create the following file: `src/components/PageWrapper.tsx` +By default, the template name is set to `default` when the `--key` option is not provided. -```tsx -// Created: 2077-01-01 -import React from 'react' - -export default PageWrapper: React.FC = (props) => { - return ( -
PageWrapper Component
- ) -} -``` +See information about each option and flag using the `--help` flag, or read the +[CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli). For information +about how configuration files work, [see below](#configuration-files). ### Configuration Files -You can also use a config file to more easily maintain all your scaffold definitions. +You can use a config file to more easily maintain all your scaffold definitions. `scaffold.config.js` @@ -99,66 +121,61 @@ module.exports = { Then call your scaffold like this: ```sh -$ npx simple-scaffold@latest -c scaffold.config.js PageWrapper +$ npx simple-scaffold -c scaffold.config.js PageWrapper ``` This will allow you to avoid needing to remember which configs are needed or to store them in a -1-liner in `packqge.json` which can get pretty long and messy, which is harder to maintain. +one-liner in `package.json` which can get pretty long and messy, and harder to maintain. Also, this allows you to define more complex scaffolds with logic without having to use the Node.js API directly. (Of course you always have the option to still do so if you wish) -See more at the [CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli) and -[Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files). +More information can be found at the +[Configuration Files documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files). -### Remote Configurations +### Templates Structure -Another quick way to start is to re-use someone else's (or your own) work using a template -repository. +Templates are **any file** in the a directory given to `--templates`. -A remote config can be loaded in one of these ways: +Simple Scaffold will maintain any file and directory structure you try to generate, while replacing +any tokens such as `{{ name }}` or other custom-data using +[Handlebars.js](https://handlebarsjs.com/). -- If it's on GitHub, you can use `-g user/repository_name` -- If it's on another git server (such as GitLab), you can use - `-g https://example.com/user/repository_name.git` +`templates/component/{{ pascalName name }}.tsx` -Configurations can hold multiple scaffold groups. Each group can be accessed using its key by -supplying the `--key` or `-k` argument, like so: +```tsx +// Created: {{ now 'yyyy-MM-dd' }} +import React from 'react' -```sh --g user/repository_name -c scaffold.js -k key_name`. +export default {{pascalCase name}}: React.FC = (props) => { + return ( +
{{pascalCase name}} Component
+ ) +} ``` -Here is an example for loading the example component templates in this very repository: +To generate the template output once without saving a configuration file, run: ```sh -$ npx simple-scaffold@latest \ - -g chenasraf/simple-scaffold \ - -k component \ - PageWrapper - -# equivalent to: -$ npx simple-scaffold@latest \ - -g https://github.com/chenasraf/simple-scaffold.git \ - -c scaffold.config.js \ - -k component \ +# generate single component +$ npx simple-scaffold \ + -t templates/component \ + -o src/components \ PageWrapper ``` -When template name (`-k component`) is omitted, `default` is used. +This will immediately create the following file: `src/components/PageWrapper.tsx` -See more at the [CLI documentation](https://chenasraf.github.io/simple-scaffold/docs/usage/cli) and -[Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files). +```tsx +// Created: 2077-01-01 +import React from 'react' -## Documentation - -See full documentation [here](https://chenasraf.github.io/simple-scaffold). - -- [Command Line Interface (CLI) usage](https://chenasraf.github.io/simple-scaffold/docs/usage/cli) -- [Node.js usage](https://chenasraf.github.io/simple-scaffold/docs/usage/node) -- [Templates](https://chenasraf.github.io/simple-scaffold/docs/usage/templates) -- [Configuration Files](https://chenasraf.github.io/simple-scaffold/docs/usage/configuration_files) -- [Migration](https://chenasraf.github.io/simple-scaffold/docs/usage/migration) +export default PageWrapper: React.FC = (props) => { + return ( +
PageWrapper Component
+ ) +} +``` ## Contributing diff --git a/docs/docs/usage/cli.md b/docs/docs/usage/cli.md index 3b23cb8..1c92f5e 100644 --- a/docs/docs/usage/cli.md +++ b/docs/docs/usage/cli.md @@ -28,6 +28,7 @@ To see this and more information anytime, add the `-h` or `--help` flag to your | `--log-level` \| `-l` | Determine amount of logs to display. The values are: `none \| debug \| info \| warn \| error`. The provided level will display messages of the same level or higher. | | `--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. | | `--help` \| `-h` | Show this help message | +| `--version` \| `-v` | Display version. | ## Examples: diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 6449b6b..d56a3a5 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -5,7 +5,7 @@ import type * as Preset from "@docusaurus/preset-classic" const config: Config = { title: "Simple Scaffold", tagline: "Generate any file structure - from single components to entire app boilerplates, with a single command.", - favicon: "img/favicon.ico", + favicon: "img/logo.svg", // Set the production url of your site here url: "https://chenasraf.github.io", diff --git a/docs/src/pages/index.module.css b/docs/src/pages/index.module.css index ff00ac8..5227ed1 100644 --- a/docs/src/pages/index.module.css +++ b/docs/src/pages/index.module.css @@ -22,3 +22,13 @@ justify-content: center; gap: 2rem; } + +.heroImage { + margin-bottom: 1.5rem; +} + +.logo { + width: 100%; + max-width: 300px; + margin: 0 auto; +} diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index a8272b7..31f17ae 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -12,10 +12,12 @@ function HomepageHeader() { return (
+ Simple Scaffold {siteConfig.title}

{siteConfig.tagline}

+ Simple-Scaffold doing its thing
API diff --git a/docs/static/img/logo-lg.svg b/docs/static/img/logo-lg.svg new file mode 100644 index 0000000..8687a4d --- /dev/null +++ b/docs/static/img/logo-lg.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + {{ + Simple + }} + + + Scaffold + + + + + diff --git a/docs/static/img/logo.svg b/docs/static/img/logo.svg index 9db6d0d..bb36361 100644 --- a/docs/static/img/logo.svg +++ b/docs/static/img/logo.svg @@ -1 +1,62 @@ - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +