add using-the-public-folder

docs/.vuepress/config.js

@@ -28,7 +28,8 @@ module.exports = {
           '/guide/adding-stylesheets',
           '/guide/adding-css-modules',
           '/guide/pre-processing-css',
-          '/guide/post-processing-css'
+          '/guide/post-processing-css',
+          '/guide/using-the-public-folder'
         ]
       },
       {

docs/guide/using-the-public-folder.md

@@ -0,0 +1,49 @@
+# Using the Public Folder
+
+You can add static assets to the `public` folder.
+
+Note that we normally encourage you to `import` assets in JavaScript files instead. This mechanism provides a number of benefits:
+
+- Scripts and stylesheets get minified and bundled together to avoid extra network requests.
+- Missing files cause compilation errors instead of 404 errors for your users.
+- Result filenames include content hashes so you don’t need to worry about browsers caching their old versions.
+
+However there is an **escape hatch** that you can use to add an asset outside of the module system.
+
+If you put a file into the `public` folder, it will **not** be processed by Webpack. Instead it will be copied into the build folder untouched. To reference assets in the `public` folder, you need to use a special variable called `PUBLIC_URL`.
+
+Inside `public/index.html`, you can use it like this:
+
+```html
+<link rel="shortcut icon" href="<%= envs.PUBLIC_URL %>/favicon.ico">
+```
+
+Only files inside the `public` folder will be accessible by `envs.PUBLIC_URL` prefix. If you need to use a file from `src` or `node_modules`, you’ll have to copy it there to explicitly specify your intention to make this file a part of the build.
+
+In JavaScript code, you can use `process.env.PUBLIC_URL` for similar purposes:
+
+```js
+render() {
+  // Note: this is an escape hatch and should be used sparingly!
+  // Normally we recommend using `import` for getting asset URLs
+  return <img src={process.env.PUBLIC_URL + '/img/logo.png'} />;
+}
+```
+
+Keep in mind the downsides of this approach:
+
+- None of the files in `public` folder get post-processed or minified.
+- Missing files will not be called at compilation time, and will cause 404 errors for your users.
+- Result filenames won’t include content hashes so you’ll need to add query arguments or rename them every time they change.
+
+## When to Use the `public` Folder
+
+Normally we recommend importing CSS, fonts, images from JavaScript.
+The `public` folder is useful as a workaround for a number of less common cases:
+
+- You need a file with a specific name in the build output, such as [`manifest.webmanifest`](https://developer.mozilla.org/en-US/docs/Web/Manifest).
+- You have thousands of images and need to dynamically reference their paths.
+- You want to include a small script like [`pace.js`](https://github.hubspot.com/pace/docs/welcome/) outside of the bundled code.
+- Some library may be incompatible with Webpack and you have no other option but to include it as a `<script>` tag.
+
+Note that if you add a `<script>` that declares global variables, you also need to read the next section on using them.