generate-examples-index-webpack-plugin/README.md

Generate an examples index page from your examples folder

# generate-examples-index-webpack-plugin

Webpack plugin to generate an index html page from the examples folder

## Installation

npm:
```
npm install -D generate-examples-index-webpack-plugin
```

yarn:
```
yarn add --dev generate-examples-index-webpack-plugin
```

## Usage

Use it as your regular webpack plugin.

```js
// webpack.config.js
const ExamplesGenerator = require('generate-examples-index-webpack-plugin');

module.exports = {
  plugins: [
    new ExamplesGenerator(),
  ],
};
```

Example of files for the `examples` folder:

* **examples/**
  * **foo/**
    * example1.ts
    * example1.html
    * example2.html
    * FooComponent.ts
  * **bar/**
    * index1.ts
    * index1.html
  * **utils/**
    * sharedFunctions.ts
    * Class1.ts
    * Class2.ts

Then, this plugin will generate a site with the following index:
* **foo/**
  * example1
  * example2
* **bar/**
  * index1

`foo/example1`, `foo/example2` and `bar/index1` are shown because there are html files which creates an entry point.

`foo/example1.html` will include `example1.ts`, and `bar/index1.html` will do the same with `bar/index1.ts`. `foo/example2` will not include nothing automatically but it can still include built files from your application like this `<script src="<% htmlWebpackPlugin.options.app %>/entryFile.js"></script>`

On the other hand, `foo/FooComponentjs` and the files inside `utils` are not shown in the index because they have no associated .html file. As you can imagine, they are just files imported by the other main ones.

Like the previously mentioned `app`, some values are provided to be used in the html templates used for the templates. You can access them placing `<% htmlWebpackPlugin.options.PLACEHOLDER %>` in the html code, being `PLACEHOLDER` one of the following values:

## Available placeholders

### Index page

| Placeholder name | Description |
|------------------|-------------|
| assets           | Route to a folder with a copy of the application build results |
| buildDate        | Date of the building time. The resulting string can be customised with the provided date options |
| examplesFolder   | Name of the original examples folder |
| examplesIndex    | HTML code with the generated examples index. Can be customised providing with the `examplesIndexHtmlGenerator` option |
| projectName      | Name of the project, directly from `project.json` |
| projectVersion   | Version of the project, directly from `project.json` |
| reportLink       | Link to the resulting report link generated if the `analyzer` option is not disabled |

### Examples pages

| Placeholder name | Description |
|------------------|-------------|
| app              | Relative path to the folder containing the results of the project build |
| assets           | Relative path to the folder with the static assets (internal from the plugin and the content from the `static` option) |
| backLink         | Relative path to the index page |
| breadcrumbs      | HTML code with the breadcrumbs for the current example
| buildDate        | Date of the building time. The resulting string can be customised with the provided date options |
| examplesFolder   | Name of the original examples folder |
| projectCss       | Relative path to the CSS file generated for the project |
| projectName      | Name of the project, directly from `project.json` |
| projectVersion   | Version of the project, directly from `project.json` |

## Options

```js
new ExamplesGenerator();
```

| Name                        | Type     | Default                      | Description |
|-----------------------------|----------|------------------------------|-------------|
| addJsExtension              | boolean  |                              | Set to `true` if your webpack options `output.filename` has no extension (because it comes from the vendor/file name). If not specified, it will try to guess the correct value from your `webpack.options.output.filename` value |
| analyzer                    | boolean  | `'assets/analyzer.html`      | Path for the file with the analysis results of your examples provided by `webpack-bundle-analyzer`. Leave undefined to disable it |
| app                         | string   | `'assets/app'`               | Where the files of your application will be placed. It's accessible via the `app` placeholder. |
| assets                      | string   | `'assets'`                   | Where the assets will be placed. |
| breadcrumbsHtmlGenerator    | function | `undefined`                  | `function(route)` returning the HTML for the breadcrumbs placeholder. Leave `undefined` to use the default one |
| buildTimeLocale             | string   | `'ja'`                       | How the date (accessible via the `buildTime` placeholder) will be outputted. Locale for `Date.toLocaleString` |
| buildTimeOptions            | object   |                              | How the date (accessible via the `buildTime` placeholder) will be outputted. Options for `Date.toLocaleString` |
| examples                    | string   | `'examples'`                 | Path were your examples are placed. Accessible with the `examplesFolder` placeholder. |
| examplesFilterHtmlGenerator | function | `undefined`                  | `function(entry)` returning the HTML for the filtering box. Leave `undefined` to use the default one |
| examplesIndexHtmlGenerator  | function | `undefined`                  | `function(entry)` returning the HTML for the examplesIndex placeholder. Leave `undefined` to use the default one |
| excludeAssets               | boolean  | `false`                      | Set to `true` to hide the assets produced by this plugin |
| extensions                  | string[] | `['js', 'jsx', 'ts', 'tsx']` | Extensions to check when finding the code file associated to an html page |
| noEntries                   | boolean  | `false`                      | Set to `true` if your project has no entry files (webpack is just used to generate examples with this plugin), to avoid the message *ERROR in Entry module not found: Error: Can't resolve './src'* |
| outputPath                  | string   | `'examplesBuild'`            | Your examples will be built and placed here |
| packageJson                 | string   | `undefined`                  | Route to the `package.json` of your application, just to retrieve information as the package name, version... If left `undefined` the plugin will try to find it automatically. It also can be an object with the data directly |
| static                      | string   | `assets`                     | Content in this folder will be copied into the `assets` path so it's accessible via the `assets` placeholder |
| templateIndex               | string   | `undefined`                  | Path with the `index.html` to use as a template. Leave `undefined` to use the default one |
| vendorContent               | string[] | `[]`                         | List of files or libraries to include in the generated vendor file |
| vendorFolder                | string   | `undefined`                  | All the files included in the folder specified by this path will be included in the vendor file |
| vendorName                  | string   | `vendor`                     | Name for the generated vendor file |

## Changelog

### 1.0.3
- Added `options.extensions` to allow other code files than `.ts` and `.js` (such as `.tsx` and `.jsx`)

### 1.0.2
- `assets` are copied only if they exist to prevent errors from `copy-webpack-plugin`

### 1.0.1
- @webpack-contrib/schema-utils moved to dependencies (not devDependencies)

### 1.0.0
- First version.