add readmeHEADmaster

1 files changed, 79 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9af422a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# material-svg-atlas-plugin-webpack
+This is a webpack plugin to generate an SVG atlas of select glyphs from the
+[Material Symbols](https://fonts.google.com/icons) library.
+
+## SVG Atlas
+An SVG atlas improves websites by storing all icons and reusable graphics in
+one place, allowing the browser to download them once and reuse them
+everywhere.
+By using an atlas, you get all your icons in one cached GET request, vs.
+potentially hundreds of GET's for individual icons.
+
+# Usage
+
+## In Webpack
+Define the plugin in your `webpack.config.js`.
+A `referenceFile` and `filename` must be defined.
+
+```js
+const path = require("path")
+const { MaterialSymbolsAtlasPlugin } = require("material-svg-atlas-plugin-webpack")
+
+const iconsJsonPath = path.resolve(iconsPath, "material-symbols.json")
+const iconsOutPath   = "icons/icons.svg"
+
+module.exports = (env, argv) => {
+    return {
+        ...
+        plugins: [
+            new MaterialSymbolsAtlasPlugin({ referenceFile: iconsJsonPath, filename: iconsOutPath }),
+        ],
+    }
+}
+```
+
+This will create an atlas at `filename` (`icons/icons.svg` in this case).
+
+## Reference File
+`referenceFile` refers to a `json` file containing the desired symbols.
+Per-symbol parameters `style`, `wght`, `grad`, `fill`, and `opsz` can be defined.
+It also allows for non-material icons to be included via using `path`.
+
+```json
+{ "refs": [
+    { "path": "./sort_by_alpha_asc.svg",  "name": "sort_by_alpha_asc"  },
+    { "path": "./sort_by_alpha_desc.svg", "name": "sort_by_alpha_desc" },
+    { "symbol": "account_circle", "fill": true },
+    { "symbol": "visibility_off", "fill": true },
+    { "symbol": "warning", "style": "rounded" },
+    { "symbol": "wysiwyg" }
+]}
+```
+
+The symbols will be downloaded from the Material Symbols database at build time
+and combined into an atlas using [svgo](https://svgo.dev/) and
+[svg-sprite](https://github.com/svg-sprite/svg-sprite).
+
+## Atlas Usage in HTML
+To use the generated atlas, you just insert an `svg` containing a `use` into your html.
+The `use` just needs to have the `href` attribute point to `{atlas}#{icon-id}`, e.g.:
+
+```html
+<svg class="white-icon">
+    <use href="icons.svg#warning"></use>
+</svg>
+```
+
+## Color
+Color can be controlled through the `fill` attribute in CSS, e.g.:
+
+```css
+.white-icon {
+    fill: white;
+}
+```
+
+# TODO
+* Version control for symbols (Material Symbols stores prior revisions of icons)
+* Global settings for symbols (weight, opsz, etc)
+* Support for [Vite](https://vite.dev/)