Skip to content

Commit

Permalink
docs: get rid of gitbook - use mkdocs and material theme
Browse files Browse the repository at this point in the history
  • Loading branch information
develar committed Jul 9, 2019
1 parent d8cfe9a commit 684f078
Show file tree
Hide file tree
Showing 23 changed files with 134 additions and 143 deletions.
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,6 @@ _book/
/CHANGELOG.md
yarn-error.log

.renderer-index-template.html
.renderer-index-template.html

/site/
38 changes: 0 additions & 38 deletions book.json

This file was deleted.

16 changes: 0 additions & 16 deletions docs/en/SUMMARY.md

This file was deleted.

54 changes: 22 additions & 32 deletions docs/en/add-ons.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,23 @@
# Add-ons

Although `electron-webpack` is provided as a single module, you can also install add-ons. Add-ons are made available to help setup certain frameworks that may require a lot of extra configuration or dependencies, such as TypeScript or Vue.js.

These add-ons are completely optional and may not support all use cases. If you need something more custom, please know that the entirety of `webpack`'s documentation still applies to `electron-webpack` ([more info](./extending-as-a-library.md)).

**Current Add-ons**
Current Add-ons:

* [JavaScript Frameworks](#javascript-frameworks)
* [Vue.js](#vuejs)
* [React JSX](#react-jsx)
* [Vue.js](#vuejs)
* [React JSX](#react-jsx)
* [Pre-processors](#pre-processors)
* [ESLint](#eslint)
* [TypeScript](#typescript)
* [Less](#less)
* [Sass/SCSS](#sassscss)
* [EJS](#ejs)
* [Nunjucks](#nunjucks)
* [ESLint](#eslint)
* [TypeScript](#typescript)
* [Less](#less)
* [Sass/SCSS](#sassscss)
* [EJS](#ejs)
* [Nunjucks](#nunjucks)
* [UI Libraries](#ui-libraries)
* [iView](#iview)
* [iView](#iview)
* [Miscellaneous](#miscellaneous)
* [Build Notifications](#build-notifications)
* [Build Notifications](#build-notifications)

---

Expand All @@ -27,16 +26,14 @@ These add-ons are completely optional and may not support all use cases. If you
### Vue.js
Adds support for Vue component files through the use of `vue-loader`. In addition, `vue-devtools` will also be installed for development purposes.

##### Install
```bash
yarn add vue electron-webpack-vue --dev
```

#### Adding TypeScript support
Install the [TypeScript](#typescript) add-on, followed by adding the below file to shim Vue component files.

#### `src/renderer/vue-shims.d.ts`
```ts
```ts tab="src/renderer/vue-shims.d.ts"
declare module '*.vue' {
import Vue from 'vue'
export default Vue
Expand All @@ -58,13 +55,12 @@ And of course, make sure to let `vue-loader` know you want to use TypeScript in
#### Adding ESLint support
Install the [ESLint](#eslint) add-on, install `eslint-plugin-html`, and add the following additional configurations.

#### Install `html` plugin to lint Vue component files
Install `html` plugin to lint Vue component files:
```bash
yarn add eslint-plugin-html --dev
```

#### `.eslintrc.js`
```js
```js tab=".eslintrc.js"
module.exports = {
plugins: [
'html'
Expand All @@ -73,7 +69,7 @@ module.exports = {
```

### React JSX
Add support for compiling JSX files.
Add support for compiling JSX files:

```bash
yarn add @babel/preset-react --dev
Expand All @@ -82,7 +78,7 @@ yarn add @babel/preset-react --dev
### Adding TypeScript support for JSX (`.tsx` files)
Install the [TypeScript](#typescript) add-on, followed by extending your `tsconfig.json` to include the jsx compiler option as below:

```json
```json tab="tsconfig.json"
{
"extends": "./node_modules/electron-webpack/tsconfig-base.json",
"compilerOptions": {
Expand All @@ -104,13 +100,13 @@ All direct dev dependencies `babel-preset-*` and `babel-plugin-*` are automatica
### ESLint
Add support for script file linting using `eslint`. Internally uses `eslint`, `eslint-loader`, `eslint-friendly-formatter`, and makes `babel-eslint` available if needed.

##### Install
```bash
yarn add electron-webpack-eslint --dev
```

##### Create `.eslintrc.js` in root directory
```js
Create `.eslintrc.js` in the root directory:

```js tab=".eslintrc.js"
module.exports = {
/* your base configuration of choice */
extends: 'eslint:recommended',
Expand All @@ -132,12 +128,11 @@ module.exports = {
### TypeScript
Add support for compiling TypeScript script files. Internally uses both `ts-loader` and `fork-ts-checker-webpack-plugin` to compile `*.ts`. Note that entry files can also use the `*.ts` extension.

##### Install
```bash
yarn add typescript electron-webpack-ts --dev
```

#### Create `tsconfig.json` in root directory
Create `tsconfig.json` in the root directory:
```json
{
"extends": "./node_modules/electron-webpack/tsconfig-base.json"
Expand All @@ -147,31 +142,27 @@ yarn add typescript electron-webpack-ts --dev
### Less
Add support for compiling Less style files.

##### Install
```bash
yarn add less less-loader --dev
```

### Sass/SCSS
Add support for compiling Sass/SCSS style files.

##### Install
```bash
yarn add node-sass sass-loader --dev
```

### EJS
Add support for compiling EJS template files.

##### Install
```bash
yarn add ejs ejs-html-loader --dev
```

### Nunjucks
Add support for compiling Nunjucks template files.
Add support for compiling Nunjucks template files:

##### Install
```bash
yarn add nunjucks nunjucks-loader --dev
```
Expand All @@ -193,7 +184,6 @@ Once you have the [element-ui](https://github.com/ElemeFE/element) installed, `e
### Build Notifications
Provide OS-level notifications from `webpack` during development.

##### Install
```bash
yarn add webpack-build-notifier --dev
```
4 changes: 0 additions & 4 deletions docs/en/books.json

This file was deleted.

3 changes: 1 addition & 2 deletions docs/en/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ One important thing to understand is that `electron-webpack` is agnostic about t

Once you have `electron-webpack` configured for your project, you can simply run the `electron-webpack` command to compile your source code. To make things easier, make use of setting up a script in your `package.json`.

```json
```json tab="package.json"
{
"scripts": {
"compile": "electron-webpack"
Expand All @@ -22,7 +22,6 @@ Now that `electron-webpack` has created your `webpack` bundle, you can simply im

#### Using `electron-builder`

##### Install
```bash
yarn add electron-builder --dev
```
Expand Down
5 changes: 1 addition & 4 deletions docs/en/cli-commands.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# CLI Commands

`electron-webpack` comes with a simple CLI to help run your application in development and compile your source code. Here is a general overview of what's available.

#### `electron-webpack dev`
Expand All @@ -16,8 +14,7 @@ Yields quick overview of all CLI features.
### Package Scripts
To make things easier, make use of setting up scripts in your `package.json` to use the CLI easier.

##### package.json
```json
```json tab="package.json"
{
"scripts": {
"dev": "electron-webpack dev",
Expand Down
2 changes: 0 additions & 2 deletions docs/en/configuration.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Configuration

As cool as `electron-webpack` can be a simple module to cover a majority of your development needs, you can also throw in your own configurations as needed. Please know that when using expected defaults, no configurations are neccessary.

Configurations can be applied in `package.json` at `electronWebpack` or in a separate `electron-webpack.(json|json5|yml)`. For the purposes of this documentation, we will use the `package.json` approach and examples will show defaults when applicable.
Expand Down
2 changes: 0 additions & 2 deletions docs/en/core-concepts.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Core Concepts

Below is a general overview of what `electron-webpack` aims to solve, and what it isn't.

#### `electron-webpack` is a module
Expand Down
6 changes: 2 additions & 4 deletions docs/en/dependency-management.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Dependency Management

When creating `electron` applications, dependency management can be a little different for specific cases. To make sure everybody is on the same page, make sure to take a look at the below documentation.

### Using `yarn`
Expand All @@ -26,7 +24,7 @@ yarn add electron-builder --dev

It may also be worth adding a `package.json` script for this command if you plan on using it often (`yarn rebuild-deps`).

```json
```json tab="package.json"
{
"scripts": {
"rebuild-deps": "electron-builder install-app-deps"
Expand All @@ -37,7 +35,7 @@ It may also be worth adding a `package.json` script for this command if you plan
If you choose not to use `electron-builder` as your build tool, you can still run the command using `npx` without side affects.

```bash
# Using `npm@^5.2.0`
# using `npm@^5.2.0`
npx electron-builder install-app-deps
```

Expand Down
18 changes: 8 additions & 10 deletions docs/en/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ yarn add electron-webpack electron webpack --dev
yarn add source-map-support
```

### Starting in development mode
### Starting in Development Mode
By default, `electron-webpack` expects, at minimum, a `main` process entry point in `src/main/index.js` ([more info](./project-structure.md)). Once you have your entry files setup, you can run `electron-webpack dev` to get started. To make things easier, make use of setting up a script in your `package.json` to start your application in development mode.

```json
```json tab="package.json"
{
"scripts": {
"dev": "electron-webpack dev"
Expand Down Expand Up @@ -39,8 +39,8 @@ yarn dev
### A little note on the *magic*
`electron-webpack` may seem like a **magical** module to some from the outside, but let's cover a few topics about what's going on *under the hood*.

##### Hot Module Replacement
Webpack HMR has been setup to support both the `renderer` and `main` process. This allows for faster development ensuring your application is only restarted when neccessary. All you need to do is accept hot updates in your entry files:
#### Hot Module Replacement
Webpack HMR has been setup to support both the `renderer` and `main` process. This allows for faster development ensuring your application is only restarted when necessary. All you need to do is accept hot updates in your entry files:

```js
// in main/index.js, renderer/index.js or in both
Expand All @@ -50,16 +50,14 @@ if (module.hot) {
```
Check out [this article](https://medium.com/@develar/electron-very-fast-developer-workflow-with-webpack-hmr-e2a2e23590ad) for more details on HMR in `electron-webpack` and the official [webpack docs](https://webpack.js.org/api/hot-module-replacement/) for details and options on the HMR API.

##### Bundling for both `renderer` and `main` processes
#### Bundling for both `renderer` and `main` processes
`webpack` is already setup to have an entry point for each process. In addition, you can also easily add further entry points to the `main` process when needed. In the other cases where you just need support for the `main` process, you can even skip the `renderer` process when needed ([more info](./configuration.md#source-directories)).

##### Use of `html-webpack-plugin`
#### Use of `html-webpack-plugin`
You might notice that you don't need an `index.html` to get started on your application. That's because it is created for you, as it adds in a few extra configurations needed for the `electron` environment. If you are creating an `electron` application with `webpack`, you are most likely creating a Single Page Application anyways. So because of that, there is already a `<div id="app"></div>` provided in the markup that you can mount your application onto.

---

#### A Note for Windows Users
### A Note for Windows Users

If you run into errors while installing dependencies, related to `node-gyp`, then you most likely do not have the proper build tools installed on your system. Build tools include items like Python and Visual Studio.

You can quickly install these build tools by globally installing [`windows-build-tools`](https://github.com/felixrieseberg/windows-build-tools). It provides many items like Visuall C++ packages, Python, and much more.
You can quickly install these build tools by globally installing [`windows-build-tools`](https://github.com/felixrieseberg/windows-build-tools). It provides many items like Visual C++ packages, Python, and much more.
5 changes: 1 addition & 4 deletions docs/en/dll-bundle-splitting.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Dll Bundle Splitting

One great feature of using `webpack` is being able to take advantage of the `webpack.DllPlugin` plugin. If you are unfamiliar with the `webpack.DllPlugin` plugin, make sure to read its [documentation](https://webpack.js.org/plugins/dll-plugin/) to better understand what problem it attempts to solve. In short, this can be used to [drastically improve](https://robertknight.github.io/posts/webpack-dll-plugins/) build time performance.

Through custom configurations `electron-webpack` provides a place to define specific packages you would like to create a separate bundle for. You can treat this feature as a way to bundle all of your *vendor* libraries together.
Expand Down Expand Up @@ -46,8 +44,7 @@ Please know that the `vendor` bundle is only created when you explicity run `ele
#### Using a `postinstall` hook
One common practice when using Dll bundle splitting to define a `postinstall` command to create the `vendor` bundle whenever new dependecies are installed. This can help ensure everything is up to date so you don't have to manually run this yourself.

##### package.json
```json
```json tab="package.json"
{
"scripts": {
"postinstall": "electron-webpack dll"
Expand Down
5 changes: 1 addition & 4 deletions docs/en/environment-variables.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Environment Variables

Sometimes you need your `webpack` build to be dependent upon specific environment variables. Whether you need to set a global API Url or even the application name, here's how you can set variables that `electron-webpack` will provide for your application.

### `ELECTRON_WEBPACK_APP_*`
Expand Down Expand Up @@ -48,7 +46,6 @@ set ELECTRON_ARGS=["--inspect-brk=9229"]&&yarn dev

Since `electron-webpack` uses the [dotenv](https://www.npmjs.com/package/dotenv) library under the hood, instead of wrestling with CLI arguments, escaping and differences between Windows and Unix systems, you can instead create an `.env` file and specify environment variables:

```bash
# file .env.development
```bash tab=".env.development"
ELECTRON_ARGS=["--inspect-brk=9229"]
```
5 changes: 1 addition & 4 deletions docs/en/extending-as-a-library.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
# Extending as a Library

One of the great benefits of using `electron-webpack` is that the entirity of `webpack`'s documentation still applies. You can easily skip using the provided CLI and modify the configurations to meet your needs. Since `electron` uses a multi-process architecture, there are also multiple `webpack` configurations. Let's cover what's provided.

### Configuration Files
Expand Down Expand Up @@ -32,8 +30,7 @@ Let's say we need to support `*.txt` files in our `renderer` process and want to
yarn add -D raw-loader
```

##### myCustomWebpack.renderer.config.js
```js
```js tab="myCustomWebpack.renderer.config.js"
const webpackRenderer = require('electron-webpack/webpack.renderer.config.js')

module.exports = env => {
Expand Down
Loading

0 comments on commit 684f078

Please sign in to comment.