docs: Update README and npm-scripts to be up to date (#134)

docs: Update README and npm-scripts to be up to date

Author: ff6347

.vscode/settings.json

@@ -1,16 +1,26 @@
 {
   "workbench.colorCustomizations": {
-    "activityBar.background": "#fb2045",
-    "activityBar.foreground": "#e7e7e7",
-    "activityBar.inactiveForeground": "#e7e7e799",
-    "activityBarBadge.background": "#115e02",
+    "activityBar.background": "#6ca2ee",
+    "activityBar.foreground": "#15202b",
+    "activityBar.inactiveForeground": "#15202b99",
+    "activityBarBadge.background": "#c81761",
     "activityBarBadge.foreground": "#e7e7e7",
-    "titleBar.activeBackground": "#e4042a",
-    "titleBar.inactiveBackground": "#e4042a99",
+    "titleBar.activeBackground": "#3e85e9",
+    "titleBar.inactiveBackground": "#3e85e999",
     "titleBar.activeForeground": "#e7e7e7",
     "titleBar.inactiveForeground": "#e7e7e799",
-    "statusBar.background": "#e4042a",
-    "statusBarItem.hoverBackground": "#fb2045",
+    "statusBar.background": "#3e85e9",
+    "statusBarItem.hoverBackground": "#6ca2ee",
     "statusBar.foreground": "#e7e7e7"
-  }
+  },
+  "peacock.color": "#3e85e9",
+  "spellright.language": [
+    "en",
+    "de"
+  ],
+  "spellright.documentTypes": [
+    "markdown",
+    "latex",
+    "plaintext"
+  ]
 }

README.md

@@ -6,48 +6,92 @@ Hosted on:
 
 [![Netlify Badge](https://www.netlify.com/img/global/badges/netlify-color-accent.svg)](https://basiljs2.netlify.com/)
 
-This repo holds the [site/docs for Basil.js](https://basiljs.github.io/)  
+This repo holds the [site/docs for Basil.js](https://basiljs.github.io/). The current state of development (develop branch) can be found here [basiljs2.netlify.com](https://basiljs2.netlify.com/)
+## Update Basil API  
+
+If there are changes to the API of Basil.js you can update the data on this repo as follows.  
+
+```bash
+
+git pull [email protected]:basiljs/basiljs.github.io.git
+cd basiljs.github.io
+# get all branches
+git fetch -a
+# get into the develop branch
+git checkout -b develop origin/develop
+# now make your new branch based on develop
+git checkout -b chore/update-docs
+# build the new data source for the site
+# This will:  
+
+# - Pull the Basil.js' branch `develop` with npm from GitHub (eventually this should be the master, not the develop branch).
+# - Generate the file `./build-scripts/api/data.json` from `./node_modules/basiljs/basil.js` using [documentation.js](http://documentation.js.org/).
+# - Generate the following files for the index.
+#    + `./_data/categories.json`
+#    + `./_data/cats-and-subcats.json`
+# - Also generate all the files for the subpages of `_source/reference`.  
+npm run build:api-markup
+# After that you can just commit all the changes and push it the repo again. Netlify will take care of the Jekyll build.  
+# Only add the files you really want to.
+# Adding all with `git add .` is acutally not the right way
+# use gits interactive mode or some more specific paths then `.`
+git add -i
+git commit -m "chore: Update Basil.js api to latest state [Add your favorite emoji here]"
+# push current HEAD to remote
+git push -u origin HEAD
+# Now go to the GitHub UI and create your PR
+```
 
-## Deploy  
+## Development
 
-If there are some changed to the API of Basil.js you can update the data on this repo as follows.  
+To build these docs we are using [Webpack](https://webpack.js.org/) and [Jekyll](https://jekyllrb.com/). You need both of these to develop on this.  
 
-    npm run build
+- Create a new branch based on branch `develop` (see the code above for a how to 👆).
+- Do your thing
+- Create a pull request against develop
 
-This will:  
+Netlify will create a branch and deploy preview for you and you can see your changes online. Every push to your branch will trigger a new build and will be linked on the PR page.
 
-- Pull the branch develop with npm from GitHub.
-- Generate the file `./.bin/api/data.json` from `./node_modules/basiljs/basil.js` using [documentation.js](http://documentation.js.org/).
-- Generate the following files for the index.
-    + `./_data/categories.json`
-    + `./_data/cats-and-subcats.json`
-- Also generate all the files for the subpages.  
+To develop locally take a look at the steps below. 👇
 
-After that you can just commit all the changes and push it the repo again. GitHub pages will take care of the jekyll build.  
+### Markup + SCSS
 
+Most of the Jekyll [liquid magic](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) happens in `./_source`.  
 
-## Development
-
-To build these docs we are using [Node.js](https://nodejs.org/en/) and [Jekyll](https://jekyllrb.com/). You need both of them installed to develop on this.  
+To develop in this run:
 
-In the `.bin/` folder you have the scripts to generate the files for the reference. The entry point is `index.js`.  
+```bash
+# once
+bundle install
+bundle update
+# whenever you want to work on the markup/content
+# (the --limit_posts 1 --incremental flags are needed
+# because we have lots of pages and need to speedup the build)
+bundle exec jekyll serve --livereload --limit_posts 1 --incremental
+```
 
-Most of the jekyll [liquid magic](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers) happens in `./index.html`, `_includes/entry-card.html`.  
+### Javascript
 
-To develop in this run:
+To work on the Javasscript of the site you need to run
 
-    bundle install
-    bundle update
-    bundle exec jekyll serve --livereload
+```bash
+# once
+# needs npm v5.7 or higer
+npm ci
+# when you develop on it
+# (starts the webpack dev watch build toolchain)
+npm run webpack:dev
+```
 
 ## Recipes
 
 Resize and crop multiple images using [`mogrify`](https://www.imagemagick.org/script/mogrify.php)  
 
-```
+```bash
 mogrify -resize 320x180^ -gravity Center -extent 320x180 -quality 100 -format png ./*/thumbnail.jpg
 
 ```
+
 ## License
 
 Copyright (c)  2013-2019 Basil.js

bootstrap-scripts/update-and-generate.sh

@@ -5,4 +5,4 @@ pwd
 npm install basiljs/basil.js#develop -D
 cp ./node_modules/basiljs/changelog.txt ./_source/download/
 npm run documentationjs -- build ./node_modules/basiljs/basil.js -o ./build-scripts/api/data.json
-node build-scripts/dist/index.js
+node build-scripts/src/index.js

package.json

@@ -9,7 +9,8 @@
     "jekyll:dev": "bundle exec jekyll serve --livereload --incremental --limit_posts 5",
     "jekyll:prod": "JEKYLL_ENV=production bundle exec jekyll build",
     "documentationjs": "documentation",
-    "update-and-generate": "sh ./bootstrap-scripts/update-and-generate.sh"
+    "update-and-generate": "sh ./bootstrap-scripts/update-and-generate.sh",
+    "build:api-markup":"npm run update-and-generate"
   },
   "repository": {
     "type": "git",