Repository: webpack-contrib/mini-css-extract-plugin (js)

Issue:
Documentation should explicitly mention that the plugin will add link for extracted CSS file if dynamically loaded.
<!--
  Issues are so 🔥

  If you remove or skip this template, you'll make the 🐼 sad and the mighty god
  of Github will appear and pile-drive the close button from a great height
  while making animal noises.

  👉🏽 Need support, advice, or help? Don't open an issue!
  Head to StackOverflow or https://gitter.im/webpack/webpack.
-->

Documentation Is:

<!-- Please place an x (no spaces!) in all [ ] that apply -->

- [x] Missing
- [ ] Needed
- [x] Confusing
- [ ] Not Sure?

### Please Explain in Detail...

I have spent couple of days trying to figure out why the styles that I was extracting using this excellent plugin were not being added to my document. Because I have a SSR site (built using larvel + larave-mix) so I don't have plugins like html-webpack-plugin. Which means the link attributes are never added.

I do know that there is this note: 
`Note: It's only applied to dynamically loaded css chunks, if you want to modify link attributes inside html file, please using html-webpack-plugin`
But this is not enough and is very missable. 

### Your Proposal for Changes

I recommend that the note be made more visible similar to warnings about using ECMA features and it's wording made more explicit. That way people will know exactly what to expect with the plugin and all of it will be less magical.

Ideally I would love an option by which link could be inserted similarly to how links are inserted for dynamically loaded CSS. That is the exact use case I have but I think there are no plans to support that feature. I do hope it would be considered as it will make things for people like me easier who want to break CSS in to smaller chunks and load them directly through JS.

Pull request description:
docs: clarify
<!--
  HOLY CRAP a Pull Request. We ❤️ those!

  If you remove or skip this template, you'll make the 🐼 sad and the mighty god
  of Github will appear and pile-drive the close button from a great height
  while making animal noises.

  Please place an x (no spaces!) in all [ ] that apply
-->

This PR contains a:

- [ ] **bugfix**
- [ ] new **feature**
- [ ] **code refactor**
- [ ] **test update** <!-- if bug or feature is checked, this should be too -->
- [ ] **typo fix**
- [x] **metadata update**

### Motivation / Use-Case

fixes #808 fixes #760

### Breaking Changes

No

### Additional Info

no

Patch:
diff --git a/README.md b/README.md
index bf483fa..82b07b1 100644
--- a/README.md
+++ b/README.md
@@ -71,19 +71,21 @@ module.exports = {
 };
 ```
 
+> ⚠️ Note that if you import CSS from your webpack entrypoint or import styles in the [initial](https://webpack.js.org/concepts/under-the-hood/#chunks) chunk, `mini-css-extract-plugin` will not load this CSS into the page. Please use [`html-webpack-plugin`](https://github.com/jantimon/html-webpack-plugin) for automatic generation `link` tags or create `index.html` file with `link` tag.
+
 ## Options
 
 ### Plugin Options
 
-|                               Name                                |         Type         |                Default                | Description                                                                   |
-| :---------------------------------------------------------------: | :------------------: | :-----------------------------------: | :---------------------------------------------------------------------------- |
-|                    **[`filename`](#filename)**                    | `{String\|Function}` |             `[name].css`              | This option determines the name of each output CSS file                       |
-|               **[`chunkFilename`](#chunkFilename)**               | `{String\|Function}` |          `based on filename`          | This option determines the name of non-entry chunk files                      |
-|                 **[`ignoreOrder`](#ignoreOrder)**                 |     `{Boolean}`      |                `false`                | Remove Order Warnings                                                         |
-|                      **[`insert`](#insert)**                      | `{String\|Function}` | `document.head.appendChild(linkTag);` | Inserts `<link>` at the given position                                        |
-|                  **[`attributes`](#attributes)**                  |      `{Object}`      |                 `{}`                  | Adds custom attributes to tag                                                 |
-|                    **[`linkType`](#linkType)**                    | `{String\|Boolean}`  |              `text/css`               | Allows loading asynchronous chunks with a custom link type                    |
-| **[`experimentalUseImportModule`](#experimentalUseImportModule)** |     `{Boolean}`      |                `false`                | Use an experimental webpack API to execute modules instead of child compilers |
+|                               Name                                |         Type         |                Default                | Description                                                                                                                               |
+| :---------------------------------------------------------------: | :------------------: | :-----------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------- |
+|                    **[`filename`](#filename)**                    | `{String\|Function}` |             `[name].css`              | This option determines the name of each output CSS file                                                                                   |
+|               **[`chunkFilename`](#chunkFilename)**               | `{String\|Function}` |          `based on filename`          | This option determines the name of non-entry chunk files                                                                                  |
+|                 **[`ignoreOrder`](#ignoreOrder)**                 |     `{Boolean}`      |                `false`                | Remove Order Warnings                                                                                                                     |
+|                      **[`insert`](#insert)**                      | `{String\|Function}` | `document.head.appendChild(linkTag);` | Inserts the `link` tag at the given position for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks |
+|                  **[`attributes`](#attributes)**                  |      `{Object}`      |                 `{}`                  | Adds custom attributes to the `link` tag for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks     |
+|                    **[`linkType`](#linkType)**                    | `{String\|Boolean}`  |              `text/css`               | Allows loading asynchronous chunks with a custom link type                                                                                |
+| **[`experimentalUseImportModule`](#experimentalUseImportModule)** |     `{Boolean}`      |                `false`                | Use an experimental webpack API to execute modules instead of child compilers                                                             |
 
 #### `filename`
 
@@ -118,6 +120,8 @@ See [examples](#remove-order-warnings) below for details.
 Type: `String|Function`
 Default: `document.head.appendChild(linkTag);`
 
+> ⚠️ Only for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) chunks.
+
 By default, the `mini-css-extract-plugin` appends styles (`<link>` elements) to `document.head` of the current `window`.
 
 However in some circumstances it might be necessary to have finer control over the append target or even delay `link` elements insertion.
@@ -169,6 +173,8 @@ A new `<link>` element will be inserted before the element with id `some-element
 Type: `Object`
 Default: `{}`
 
+> ⚠️ Only for [non-initial (async)](https://webpack.js.org/concepts/under-the-hood/#chunks) chunks.
+
 If defined, the `mini-css-extract-plugin` will attach given attributes with their values on `<link>` element.
 
 **webpack.config.js**
diff --git a/src/plugin-options.json b/src/plugin-options.json
index 7a4ce2c..e4f61e0 100644
--- a/src/plugin-options.json
+++ b/src/plugin-options.json
@@ -38,7 +38,7 @@
       "link": "https://github.com/webpack-contrib/mini-css-extract-plugin#ignoreorder"
     },
     "insert": {
-      "description": "Inserts `<link>` at the given position.",
+      "description": "Inserts the `link` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.",
       "link": "https://github.com/webpack-contrib/mini-css-extract-plugin#insert",
       "anyOf": [
         {
@@ -50,7 +50,7 @@
       ]
     },
     "attributes": {
-      "description": "Adds custom attributes to tag.",
+      "description": "Adds custom attributes to the `link` tag for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.",
       "link": "https://github.com/webpack-contrib/mini-css-extract-plugin#attributes",
       "type": "object"
     },


Test patch:
diff --git a/test/__snapshots__/validate-plugin-options.test.js.snap b/test/__snapshots__/validate-plugin-options.test.js.snap
index 8894c2b..185a3c4 100644
--- a/test/__snapshots__/validate-plugin-options.test.js.snap
+++ b/test/__snapshots__/validate-plugin-options.test.js.snap
@@ -4,7 +4,7 @@ exports[`validate options should throw an error on the "attributes" option with
 "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema.
  - options.attributes should be an object:
    object { … }
-   -> Adds custom attributes to tag.
+   -> Adds custom attributes to the \`link\` tag for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.
    -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#attributes"
 `;
 
@@ -41,7 +41,7 @@ exports[`validate options should throw an error on the "insert" option with "{}"
 "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema.
  - options.insert should be one of these:
    string | function
-   -> Inserts \`<link>\` at the given position.
+   -> Inserts the \`link\` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.
    -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#insert
    Details:
     * options.insert should be a string.
@@ -52,7 +52,7 @@ exports[`validate options should throw an error on the "insert" option with "1"
 "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema.
  - options.insert should be one of these:
    string | function
-   -> Inserts \`<link>\` at the given position.
+   -> Inserts the \`link\` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.
    -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#insert
    Details:
     * options.insert should be a string.
@@ -63,7 +63,7 @@ exports[`validate options should throw an error on the "insert" option with "tru
 "Invalid options object. Mini CSS Extract Plugin has been initialized using an options object that does not match the API schema.
  - options.insert should be one of these:
    string | function
-   -> Inserts \`<link>\` at the given position.
+   -> Inserts the \`link\` tag at the given position for non-initial (async) (https://webpack.js.org/concepts/under-the-hood/#chunks) CSS chunks.
    -> Read more at https://github.com/webpack-contrib/mini-css-extract-plugin#insert
    Details:
     * options.insert should be a string.