Merge pull request #207 from TheComputerM/docs/installation-updates

Docs/installation updates

Author: Florian-Schoenherr

packages/docs/src/routes/getting-started/contributing.md

@@ -10,25 +10,26 @@ If you would like to contribute to svelte materialify and improve its functional
 
 ## Reporting Issues
 
-It is important to keep your setup to a **minimum** so if you can it is better to reproduce the bug in the [repl playground](https://svelte.dev/repl/2c55788d8ffd4458bfe9bcb5f58956db). Before reporting an issue, ensure that:
+Before reporting an issue, ensure that you:
 
-- Search for a similar [issues](https://github.com/TheComputerM/svelte-materialify/issues), it may have been answered.
+- searched for similar [issues](https://github.com/TheComputerM/svelte-materialify/issues), it may have been answered already
 
-- Reproduction as to be **minimal** and consise.
+- have a **minimal**, concise, reproducible example
 
-- If possible try running the code in the [repl playground](https://svelte.dev/repl/2c55788d8ffd4458bfe9bcb5f58956db).
+- have tried providing a [REPL](https://svelte.dev/repl/9982308600f043f3aeb43fb3b17f35b5?version=3.37.0)
 
-## Setting up your environment
+## Working on Svelte Materialify
+### Setting up your environment
 
 Follow these instructions if you are planning to make a pull request.
 
-## Get the source
+### Getting the source
 
-1.  Register to [github](https://github.com/).
+1.  Register to [Github](https://github.com/)
 2.  Navigate to [svelte-materialify](https://github.com/TheComputerM/svelte-materialify)
 3.  Press the fork button in the top right corner of the screen
-4.  Copy the url of your browser, it should now be : https://github.com/**your_github_user_id**/svelte-materialify
-5.  On your PC open a command prompt window and type the following commands
+4.  Copy the url of your browser, it should now be: `https://github.com/{your_github_user_id}/svelte-materialify`
+5.  On your PC, open a command prompt window and type the following commands
 
 ```shell
 $ git clone https://github.com/{your_github_user_id}/svelte-materialify.git
@@ -37,39 +38,48 @@ $ cd svelte-materialify
 
 This will get the entire repository on your machine, now we can build the library.
 
-## Build
+### Building
 
 Building is done with yarn (**not** npm).
-From the root folder, install the dependencies by typing:
+From the **root folder**, install the dependencies by typing:
 
 ```shell
 yarn
 ```
 
-Then to build the main library, svelte materialify itself.
+Then build the main library, svelte materialify, itself:
 
 ```shell
 yarn build
 ```
 
-To build and develop the documentation site.
+To build and develop the documentation site:
 
 ```shell
 yarn dev
 ```
 
-Then you can build the API, which provides the definitions and types for the different props/events/slots for the components.
+To build the API, which provides the definitions and types for the different props/events/slots of the components:
 
 ```shell
 yarn api
 ```
 
-## Submit your change
+### Submitting your change
 
-First make a change and make sure it works well by running `yarn lint` and `yarn test`, then commit your changes following [this syntax](https://github.com/conventional-changelog/commitlint/#what-is-commitlint).
-
-For example here
+After making a change, make sure it works well by running:
+```shell
+yarn lint
+```
+and
+```shell
+yarn test
+```
+Please commit your changes following [conventional commit syntax](https://github.com/conventional-changelog/commitlint/#what-is-commitlint), for example:
+```shell
+git commit -m "docs: improve contributing.md"
+```
 
-`docs: improve contributing.md`
+Then, **git push** your changes to your github repository.
 
-Then push your changes to your github repository, finally from the github repository web page you can click the Pull Request button and a contributor will review the changes you made.
+Finally, from the github repository web page, you can click the **Pull Request** button and a contributor will review the changes you made.

packages/docs/src/routes/getting-started/installation.md

@@ -10,65 +10,47 @@ related:
 
 # Installation
 
-Get Started with Svelte Materialify, the best material UI component library for Svelte
+Get Started with Svelte Materialify, the best material UI component library for Svelte.
 
-If you want to try out svelte materialify and tinker with it, visit the [repl playground](https://svelte.dev/repl/2c55788d8ffd4458bfe9bcb5f58956db).
+If you want to try out svelte materialify and tinker with it, visit the [REPL playground](https://svelte.dev/repl/2c55788d8ffd4458bfe9bcb5f58956db).
 
-We can also **optionally** add [focus-visible](https://github.com/WICG/focus-visible), if you want keyboard focused styles.
+You can also **optionally** add [focus-visible](https://github.com/WICG/focus-visible), if you want keyboard focused styles.
 
 ```html
 <script src="https://unpkg.com/focus-visible@latest/dist/focus-visible.min.js"></script>
 ```
 
-## Minimal Install
+## Install with Default Styles
 
-If want a fast and basic setup then only installing `svelte-materialify` should be fine.
+If you want a fast and basic setup, without custom SCSS/SASS, then only installing `svelte-materialify` should be fine:
 
 ```shell
 $ npm i svelte-materialify
 ```
 
-And then in your svelte files, import the compiled module for svelte materialify
+## Install with Custom Styles
 
-```html
-<script>
-  // In a svelte file
-  // Import Everything
-  import * as S from 'svelte-materialify';
-  // OR
-  import { Button } from 'svelte-materialify';
-  // Import a single component
-</script>
-```
-
-## Advanced Install
-
-If you want finer control over Svelte Materialify and installation you want to install all its peer dependencies.
+If you want finer control over Svelte Materialify, install all its peer dependencies:
 
 ```shell
 $ npm i -D svelte-materialify svelte-preprocess sass postcss
 ```
 
-```html
-<script>
-  // In a svelte file
-  // Import Everything from svelte-materialify/src
-  import * as S from 'svelte-materialify/src';
-  // OR
-  import { Button } from 'svelte-materialify/src';
-  // Import a single component
-</script>
-```
-
-<Components.Alert type='info'>
-
-Now _you_ can also use SCSS and SASS styles in your own components. Learn more about [svelte-preprocess](https://github.com/sveltejs/svelte-preprocess/blob/master/docs/usage.md).
+Now create a **\_material-theme.scss** file. Let's put it in a folder called **theme**.
 
-</Components.Alert>
+Include the folder path in the `sveltePreprocess` function in your **rollup.config.js**:
 
-Then create a **\_material-theme.scss** file and place it in any folder, lets put it in a folder called **theme**. Then include the path in the preprocess function in your **rollup.config.js** (likewise follow the same in webpack but for svelte-loader).
+```js
+svelte({
+  preprocess: sveltePreprocess({
+    scss: {
+      includePaths: ['theme'],
+    },
+  }),
+  ...
+```
 
-Now add a **svelte.config.js** to add to the root of the project to provide better intellisense.
+For better intellisense, you can instead create a **svelte.config.js** and add it to the root of the project:
 
 ```js
 const sveltePreprocess = require('svelte-preprocess');
@@ -81,7 +63,7 @@ module.exports = {
   }),
 };
 ```
-
+Now you can import this file from your main config file, like shown below:
 ### Rollup
 
 ```js
@@ -126,7 +108,7 @@ Learn how to integrate svelte materialify with existing frameworks.
 
 #### Sapper
 
-Add preprocessor for both client and server bundles.
+Add the preprocessor for both client and server bundles:
 
 ```js
 const { preprocess } = require('./svelte.config');
@@ -150,4 +132,20 @@ export default {
 };
 ```
 
+#### Sveltekit
+
+See: https://github.com/TheComputerM/sveltekit-materialify
 ## Templates
+
+Basic setup done for you:
+
+### Sveltekit
+
+```
+npx degit TheComputerM/sveltekit-materialify my-sveltematerialify-project
+
+cd my-svelte-project
+
+npm install
+npm run dev
+```

packages/docs/src/routes/getting-started/usage.md

@@ -9,16 +9,45 @@ related:
 
 # Usage
 
-Once you have installed Svelte Materialify and other dependencies, it is time to learn how to use it.
+Once you have installed Svelte Materialify, it's time to learn how to use it.
 
+## Importing the Components
+Depending on the Install you chose, there are two ways to import:
+### With Default styles
+
+In your svelte files, import the _compiled_ module `from 'svelte-materialify'`:
+
+```html
+<script>
+  import { MaterialApp, Button } from 'svelte-materialify';
+</script>
+
+<MaterialApp>
+  <Button>Compiled (Default styles, used in the REPL)</Button>
+</MaterialApp>
+```
+### With Custom styles
+
+In your svelte files, import the _uncompiled_ module `from 'svelte-materialify/src'`:
+
+```html
+<script>
+  import { MaterialApp, Button } from 'svelte-materialify/src';
+  //this works, too:
+  import Button from 'svelte-materialify/src/components/Button/Button.svelte';
+</script>
+
+<MaterialApp>
+  <Button>Uncompiled (Custom styles, defined in _material-theme.scss)</Button>
+</MaterialApp>
+```
 ## Layout
 
-All components should be children of `MaterialApp` which has all the global styles and
-enables theming.
+All components should be children of `MaterialApp`, which provides all the **global styles** and enables theming:
 
 ```html
 <script>
-  import { MaterialApp } from 'svelte-materialify';
+  import { MaterialApp } from 'svelte-materialify'; //or from `/src`
   let theme = 'light';
 </script>
 
@@ -27,39 +56,44 @@ enables theming.
 </MaterialApp>
 ```
 
+If you don't want any global styles (other than theming and colors), you can use `MaterialAppMin` instead:
+
+```html
+<script>
+  import { MaterialAppMin } from 'svelte-materialify'; //or from `/src`
+  let theme = 'light';
+</script>
+
+<MaterialAppMin theme="{theme}">
+  <slot />
+</MaterialAppMin>
+```
+
 ## Theming
 
-What to customise some SCSS variables, worry not, just put them in the **\_material-theme.scss** you had created.
+You want to customise some SCSS variables?
+Worry not, just put them in the **\_material-theme.scss** you had created:
 
 ```scss
+$primary-color: #004d26;
+$secondary-color: #ff99cc;
+$error-color: #420420;
+$success-color: #66ff99;
+
 $body-font-family: "Poppins", "Segoe UI", sans-serif;
 
 $spacer: 6px !default;
 ...
 ```
 
-To access these variables in your own components just import the variable file from svelte materialify.
+To access these variables in your own components, just import the variable file from svelte materialify:
 
 ```scss
 @import 'svelte-materialify/src/styles/variables';
 ```
 
-## Components
-
-Just import them one by one or all at once from svelte materialify.
-
-```html
-<script>
-  import * as S from 'svelte-materialify';
-
-  import { Button } from 'svelte-materialify';
-  // OR import from source
-  import { Button } from 'svelte-materialify/src';
-  // OR directly import the button component
-  import Button from 'svelte-materialify/src/components/Button/index.js';
-</script>
+<Components.Alert type='info'>
 
-<S.Button>These Are</S.Button>
+If you want to use SCSS and SASS styles in your own components, [use svelte-preprocess](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/usage.md).
 
-<button>The Same Thing</button>
-```
+</Components.Alert>