Updating documentation

blog/gulp.md

@@ -62,8 +62,18 @@ The `gulp` command should be followed by the name of the export you want to run.
 
 You can then run the command using `npm` or `yarn`: `yarn buildSearch`.
 
+## promises in gulp functions
+
+Gulp functions must take `cb` as a parameter and end with `cb()` to let gulp know the task has finished.
+
+Alternatively you can use an `async` function and have your function `await` a promise at the end.
+
+**If your function ends with a promise you do not need to use `cb()`**.
+
 ## webpack
 
+### webpack api
+
 You can integrate gulp with webpack, allowing gulp to run your webpack build. There are a few ways to do this, one way using `webpack-stream` is here: <https://cecilphillip.com/adding-webpack-to-your-gulp-tasks/>.
 
 Alternatively, if you don't want to control webpack through gulp (pipe in a different destination or alter the workflow) and just want to run it as if you were running webpack directly you can simply import `webpack` and your `webpack.prod.js` file into gulp.
@@ -92,3 +102,113 @@ module.exports = {
   buildTheme: buildTheme,
 };
 ```
+
+### using exec
+
+TODO: Link this to javascript running commands/executing files.
+
+If you wanted to run a webpack build in another node project (say a theme which is a submodule), you can use `exec` to literally run the webpack command from the folder as if you were doing it on the shell.
+
+```javascript
+const util = require("util");
+const exec = util.promisify(require("child_process").exec);
+
+const themeDir = getCurrentDir(__dirname) + "/themes/panaetius-theme";
+
+function getCurrentDir(dir) {
+  var themeDir = dir.split("/");
+  themeDir.pop();
+  return themeDir.join("/");
+}
+
+// Function to build the theme
+async function buildTheme(cb) {
+  console.log(themeDir);
+  await exec(
+    `cd ${themeDir} && node ${themeDir}/node_modules/webpack/bin/webpack.js --config ${themeDir}/webpack.prod.js`
+  );
+}
+```
+
+Here we are getting the current full path to the file being ran (the gulpfile) and stripping the filename to get the path.
+
+We then use `exec`, which has been wrapped in a promise, to `cd` into the project directory and run the node command to build webpack.
+
+## minimizing images
+
+<https://gulpjs.com/docs/en/getting-started/working-with-files>
+
+Use the plugin `gulp-imagemin`: `yarn add gulp-imagemin`
+
+You should use `src()` and `dest()` using `pipe()` to load in your images.
+
+`src` should be an array of images (you can use globs). You then pipe into an instance of `imagemin()`.
+
+To overwrite the file, you should use `file.base` in a function:
+
+```javascript
+function minifyImages(cb) {
+  gulp
+    .src([
+      `${currentDir}/content/**/*.png`,
+      `${currentDir}/content/**/*.svg`,
+      `${currentDir}/static/**/*.png`,
+      `${currentDir}/static/**/*.svg`,
+      `${themeDir}/static/**/*.png`,
+      `${themeDir}/static/**/*.svg`,
+    ])
+    .pipe(imagemin())
+    .pipe(
+      gulp.dest(function (file) {
+        return file.base;
+      })
+    );
+  cb();
+}
+```
+
+## minimizing javascript
+
+Some javascript won't be suitable for inclusion in a bundle (`lunr`). You can include these in your final build by copying the file from `node_modules` into `./static/dist` and minimize the file using gulp.
+
+Use `yarn add gulp-minify`.
+
+```javascript
+const minify = require("gulp-minify")
+
+function lunr(cb) {
+  gulp
+    .src(`${currentDir}/node_modules/lunr/lunr.js`)
+    .pipe(minify())
+    .pipe(gulp.dest(`${currentDir}/static/dist`));
+  cb();
+}
+```
+
+## inserting webpack dynamic bundle content into a file
+
+<https://stackoverflow.com/questions/23247642/modify-file-in-place-same-dest-using-gulp-js-and-a-globbing-pattern>
+
+Use <https://www.npmjs.com/package/gulp-replace> to replace a string in a file.
+
+Approach:
+If you are not using Hugo, you could use the above to dynamically reference images in your html.
+
+Use gulp to replace these references with the images bundled with webpack. If yuo name the images the same as they're referenced, then replace any `<img src="">` with the bundled image in the html.
+
+You can get the mapping from the output from webpack, using the unique image name as the key. You can then use gulp to minimise or resize the images.
+
+## Hugo
+
+TODO: Link this to javascript running commands/executing files.
+
+You can build a Hugo project in Gulp by using `execFile`.
+
+```javascript
+const util = require("util");
+const exec = util.promisify(require("child_process").execFile);
+
+async function buildHugo(cb) {
+  await execFile("hugo", ["-D", "--minify"]);
+}
+```

blog/javascript.md

@@ -0,0 +1,53 @@
+# Javascript
+
+## Promises
+
+### wrapping a method/function in a promise
+
+If a method you are importing does not return a promise, you can wrap it in one so you can use `async` `await`.
+
+```javascript
+const util = require("util");
+const execFile = util.promisify(require("child_process").execFile);
+```
+
+Use `util.promisify` on the `import`/`require` to wrap it in a promise.
+
+## await multiple tasks at the same time
+
+You do not have to sequentially `await` functions in turn. It is possible to fire off multiple at the same time and then wait for them all to finish:
+
+```javascript
+let [foo, bar] = await Promise.all([getFoo(), getBar()]);
+```
+
+You wrap each function you want in `Promise.all()` - this takes an array of promises, and composes them all into a single promise. This will only resolve when every promise in the array has resolved itself.
+
+**Important** - `Promise.all()` does not _dispatch_ or _do_ the promises, it only waits on them. This is why in the example above we are calling them in the array. If we don't call them we would have to call them later (from another function) since it would pause here and wait for them to complete.
+
+## dispatch a promise and await it later
+
+It is possible to dispatch a promise to run asynchronously, and continue on with your function. Later on in the function you can `await` it and get the results.
+
+This is really useful if your function does a job remotely and you want to do something else while it gets the results:
+
+```javascript
+async function buildSearch(cb) {
+  // run() returns a promise
+  let searchIndex = run();
+  //   do something...
+  let searchIndexResult = await searchIndex;
+}
+```
+
+## Writing to files
+
+You can write a string/json object to a file:
+
+```javascript
+async function buildSearch() {
+  // index is a js object
+  let searchIndex = JSON.stringify(index);
+  fs.writeFileSync(currentDir + "/static/search-index.json", searchIndex);
+}
+```

blog/package.json

@@ -1,6 +1,12 @@
 {
   "dependencies": {
     "gulp": "^4.0.2",
+    "gulp-clean": "^0.4.0",
+    "gulp-hash-filename": "^3.0.0",
+    "gulp-imagemin": "^7.1.0",
+    "gulp-rename": "^2.0.0",
+    "gulp-replace": "^1.0.0",
+    "gulp-uglify": "^3.0.2",
     "lunr": "^2.3.8",
     "parser-front-matter": "^1.6.4",
     "readdirp": "^3.4.0",
@@ -10,6 +16,10 @@
     "buildSearch": "gulp buildSearch",
     "buildHugo": "gulp buildHugo",
     "buildBlog": "gulp buildBlog",
-    "buildTheme": "gulp buildTheme"
+    "buildTheme": "gulp buildTheme",
+    "cleanJS": "gulp cleanJS",
+    "insertJS": "gulp insertJS",
+    "lunr": "gulp lunr",
+    "minifyImages": "gulp minifyImages"
   }
 }

blog/todo-webpack.todo

@@ -20,14 +20,17 @@ Search:
   ☐ Have search auto run whenever a button is pressed
 
 Gulp:
-  ☐ Using <https://stackoverflow.com/questions/23247642/modify-file-in-place-same-dest-using-gulp-js-and-a-globbing-pattern> and <https://www.npmjs.com/package/gulp-replace> to handle hashed images.
+  ✔ Using <https://stackoverflow.com/questions/23247642/modify-file-in-place-same-dest-using-gulp-js-and-a-globbing-pattern> and <https://www.npmjs.com/package/gulp-replace> to handle hashed images. @done (6/4/2020, 1:28:15 AM)
   Notes:
-    ☐ If you are not using Hugo, you could use the above to dynamically reference images in your html, and use gulp to replace them with the images bundled with webpack. Name the images the same as they're referenced, then replace any `<img src="">` with the bundled image in the html. You can get the mapping from the output from webpack, using the unique image name as the key.. You can then use gulp to minimise or resize the images.
+    ✔ If you are not using Hugo, you could use the above to dynamically reference images in your html, and use gulp to replace them with the images bundled with webpack. Name the images the same as they're referenced, then replace any `<img src="">` with the bundled image in the html. You can get the mapping from the output from webpack, using the unique image name as the key.. You can then use gulp to minimise or resize the images. @done (6/4/2020, 1:28:13 AM)
-    ☐ Hugo will bundle your images into their own folders. You can use gulp to find images in your `./posts` (or even the whole project), and resize/minimise them.
+    ✔ Hugo will bundle your images into their own folders. You can use gulp to find images in your `./posts` (or even the whole project), and resize/minimise them. @done (6/4/2020, 1:23:48 AM)
-  ☐ Document everything in notes
+  ✔ Document everything in notes @done (6/3/2020, 7:20:55 PM)
-  ☐ Have search job save to a file.
+  ✔ Have search job save to a file. @done (6/3/2020, 7:20:55 PM)
   ✔ Document yarn automatically resolving modules locally for commands you give it (running gulp it will automaitcally find it). @done (6/3/2020, 1:21:46 AM)
   ✔ Document javascript exports using ES6. @done (6/3/2020, 1:21:47 AM)
   ✔ Using the cjs extension for gulpfile.or using type: module in package.json. @done (6/3/2020, 1:21:48 AM)
   Notes:
     ✔ When can we use require vs import? @done (6/3/2020, 1:21:49 AM)
+
+Hugo:
+  ✔ Add 3 image locations to documentation (./static/images, ./theme/static/dist, ./content) @done (6/4/2020, 1:30:34 AM)

blog/webpack-filestructure.md

@@ -20,13 +20,15 @@ Overview:
 
 The structure can depend on the project. If you are using webpack you can create `./src` folder where you can place `./src/js` or `./src/scss` for example. We can have a `./node_modules` folder then use webpack to compile.
 
+Images/content to be bundled by webpack (used in the css) go in `./src`.
+
 You can use a layout suggestion as given here: <https://medium.com/@nmayurashok/file-and-folder-structure-for-web-development-8c5c83810a5> for inside the `./src` folder.
 
 ### Files location
 
 Raw files go in `./src` or at the root level. See the folder structure on how to name folders.
 
-Any bundled/compiled files which will be used by the website itself should go in `./dist` or `./static/dist`.
+Any bundled/compiled files which will be used by the website itself should go in `./dist` or `./static/dist`. You can also place content that goes outside the bundle (extra images not referenced in css) in `./static/images`.
 
 ## Build patterns/ code organisation