SKC-18 custom settings template

.gitignore

@@ -1,4 +1,5 @@
 *.priv.js
+*.cust.js
 
 ### Node ###
 # Logs

README.md

@@ -604,16 +604,31 @@ Building `surfingkeys-conf` requires a few dependencies to be installed:
 	```shell
 	$ vim ./conf.priv.js
 	```
+
+4. __*(Optional)* Own Custom Mappings & Settings Configuration__
+    Own custom settings & mappings can be placed in one file without touching
+    the core files.
+	Copy the example custom configuration:
 
-4. __Gulp Build/Install__
+	```shell
+	$ cp ./conf.cust.example.js ./conf.cust.js
+	```
+
+	Open `./conf.cust.js` in your favorite editor and follow the instructions inside:
+
+	```shell
+	$ vim ./conf.cust.js
+	```
+
+5. __Gulp Build/Install__
 	```shell
 	$ gulp install # OR "gulp build" to build to ./build/surfingkeys.js without installing
 	```
 
 	This will build the final configuration file and place it at `~/.config/surfingkeys.js`.
 	If you already have a file in that location, make sure you back it up first!
 
-5. __Load your configuration into the SurfingKeys Extension__
+6. __Load your configuration into the SurfingKeys Extension__
 
 	<details>
 	<summary><strong>Option A</strong> <em>(recommended)</em>: Configure SurfingKeys to automatically load configuration file from disk</summary>

conf.cust.example.js

@@ -0,0 +1,54 @@
+/*
+Place for any custom settings/mappings (mostly documented on https://github.com/brookhong/Surfingkeys
+ */
+
+// const { categories } = require("./help")
+// mappings must go in this specific format
+const maps = {
+  /*
+  define mappings in format:
+   "domain.com": [ // or just "general"
+     {
+       alias: "", // here keybinding
+       category: 0, // best from the categories requirement
+       description: "The description of the mapping", // self explanatory
+       // Now either of the:
+       map: "", // the key remapping, of:
+       callback: () => {} // the callback
+     }
+   ]
+   */
+
+}
+// note that every alias key has to be present in the maps keys
+const aliases = {
+  /*
+    "domain.com": [
+      "example.com" // also known as
+    ]
+   */
+}
+// custom settings (for example: theme)
+const conf = {
+  /*
+    theme: 'body: { bg-color: "black" }'
+   */
+}
+
+// miscellanous entries
+const leaders = {
+  /*
+    site: "",
+    search: "",
+   */
+}
+
+const hints = ""
+
+module.exports = {
+  maps,
+  aliases,
+  conf,
+  leaders,
+  hints
+}

conf.js

@@ -1,6 +1,7 @@
 const util = require("./util")
 const keys = require("./keys")
 const completions = require("./completions")
+const custom = require("./conf.cust")
 
 // ---- Settings ----//
 util.addSettings({
@@ -18,15 +19,17 @@ util.addSettings({
   `,
 })
 
+util.addSettings(custom.conf || {})
+
 if (typeof Hints !== "undefined") {
-  Hints.characters = "qwertasdfgzxcvb"
+  Hints.characters = custom.hints || "qwertasdfgzxcvb"
 }
 
 // Leader for site-specific mappings
-const siteleader = "<Space>"
+const siteleader = custom.leaders.site || "<Space>"
 
 // Leader for OmniBar searchEngines
-const searchleader = "a"
+const searchleader = custom.leaders.search || "a"
 
 // Process mappings and completions
 // See ./keys.js and ./completions.js

gulpfile.js

@@ -37,7 +37,7 @@ const requireSrcFiles = () => {
 }
 
 const paths = {
-  scripts:     ["conf.priv.js", "completions.js", "conf.js", "actions.js", "help.js", "keys.js", "util.js"],
+  scripts:     ["conf.priv.js", "conf.cust.js", "completions.js", "conf.js", "actions.js", "help.js", "keys.js", "util.js"],
   entry:       "conf.js",
   gulpfile:    "gulpfile.js",
   readme:      "README.tmpl.md",
@@ -88,6 +88,17 @@ task("check-priv", async () => {
   return Promise.resolve()
 })
 
+task("check-cust", async () => {
+  try {
+    await fs.stat("./conf.cust.js")
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.log("Notice: Initializing ./conf.cust.js - configure your custom settings & mappings here.")
+    return fs.copyFile("./conf.cust.example.js", "./conf.cust.js", COPYFILE_EXCL)
+  }
+  return Promise.resolve()
+})
+
 task("docs", parallel(async () => {
   requireSrcFiles()
 
@@ -236,6 +247,7 @@ task("build",
   series(
     parallel(
       "check-priv",
+      "check-cust",
       "clean",
     ),
     parallel(

keys.js

@@ -1,5 +1,6 @@
 const actions = require("./actions")
 const { categories } = require("./help")
+const custom = require("./conf.cust")
 
 // Remove undesired default mappings
 const unmaps = {
@@ -608,6 +609,12 @@ const maps = {
   ],
 }
 
+const customMaps = Object.entries(custom.maps || {})
+
+customMaps.forEach((m) => {
+  maps[m[0]] = (maps[m[0]] || []).concat(m[1])
+})
+
 // Aliases
 const aliases = {
   "wikipedia.org": [
@@ -637,6 +644,8 @@ const aliases = {
   ],
 }
 
+Object.assign(aliases, custom.aliases || {})
+
 module.exports = {
   unmaps,
   maps,