Updating documentation

.vscode/settings.json

@@ -5,9 +5,10 @@
         "editor.defaultFormatter": "HookyQR.beautify"
     },
     "[handlebars]": {
-
     },
     "beautify.config": {
         "indent_handlebars": false
     },
+    "twig-language-2.endComma": "always",
 }
+

blog/config.toml

@@ -1,4 +1,4 @@
-baseURL = "http://example.org/"
+baseURL = "http://127.0.0.1:6060"
 title = "panaetius.io"
 theme = "hugo-theme-chunky-poster"
 paginate = 2
@@ -8,9 +8,12 @@ enableInlineShortcodes = true
 footnoteReturnLinkContents = "^"
 description = "Tech blog showcasing Python, Machine-Learning, Vue, Homelab and other technologies to try at home."
 
+
 [languages]
+
 [lanugages.en]
 weight = 1
+
 [languages.en.params]
 LanguageName = "English"
 
@@ -55,7 +58,6 @@ logo = "/images/homepage.svg"
 share = true
 twitter = "dmot7291"
 github = "dtomlinson91"
-
 # Custom CSS and JS. Relative to /static/css and /static/js respectively.
 customCSS = []
 customJS = []
@@ -73,3 +75,8 @@ resampleFilter = "Lanczos"
 [outputs]
 home = ["HTML", "RSS", "JSON"]
 page = ["HTML", "RSS"]
+
+[markup]
+
+[markup.highlight]
+style = "fruity"

blog/webpack-config.md

@@ -0,0 +1,34 @@
+### Webpack config setup
+
+`output.path` is where the bundles files will go
+is `output.publicPath` the path you will reference in the `html`. Here is a webpack wiki explanation: <https://github.com/webpack/docs/wiki/configuration#outputpublicpath>.
+
+### Use npm to install bower dependencies
+
+As `bower` is deprecated in favour of `yarn` and `webpack`, most packages now come with `npm`.`yarn`.
+
+You can use `npm` to install bower dependencies if they are old and haven't been updated for `npm`.
+
+#### Change bower installation path
+
+You should change the installation path for `bower` from `bower_modules` to `node_modules`.
+
+To do this create a `.bowerrc` file in the root of your repo that contains the following:
+
+```json
+{
+  "directory" : "node_modules"
+}
+```
+
+#### Allow npm to run bower install
+
+You can use an `npm` script to run `bower install` which will install your bower dependencies whenever you do `npm install`.
+
+Edit the `scripts` in your `package.json` to add the following:
+
+```json
+"scripts": {
+  "postinstall": "bower install"
+}
+```

blog/webpack-filestructure.md

@@ -0,0 +1,269 @@
+# Webpack
+
+TODO: This note should also go under a note for structuring a website.s
+
+Great tutorial for the basics: <https://www.sitepoint.com/bundle-static-site-webpack/>.
+
+We can use webpack to bundle up our resources (javascript files or css files) and create a minified bundle for a website.
+
+You can bundle anything up, we can even write `scss` and have webpack lint, compile and minify into the `dist` directory for us automatically.
+
+## Structure
+
+### Folder structure
+
+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.
+
+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`.
+
+## Build patterns/ code organisation
+
+### SCSS/CSS
+
+Any scss/css you want to use should go in your `./src/scss` folder (or wherever else it is going).
+
+You should have a `_variables.scss` which should define and/or overwrite any variables from any frameworks you are importing (bootstrap).
+
+You can then have as many `scss` files as needed for your content. You can split them by page, or by component etc.
+
+Finally you should have a `styles.scss`. This file should import all the `scss` files you've created, in addition to any provided by third party packages. Remember to import the `_variables.scss` file first and any other `scss` files that are needing to be overwritten by these variables afterwards.
+
+TODO: Link to the example `styles.scss` in git.
+
+With `scss`, imports are done with the `@import "";` syntax. You leave out the extension if it's `.scss`, otherwise provide it if it's `css`.
+
+If you want to reference a file in `node_modules` you can use the `~` as a shortcut to that path. E.g `@import "~bootstrap/scss/bootstrap";`.
+
+```scss
+@import "_variables";
+@import "~bootstrap/scss/bootstrap";
+@import "~ekko-lightbox/dist/ekko-lightbox.css";
+```
+
+### Javascript
+
+You should use asynchronous imports to improve performance in your `.js` files.
+
+We create two files: `App.js` and `main.js`.
+
+#### App.js
+
+TODO: Link to the `App.js` file in git
+
+This file should go in `./src/js`. It should contain all the javascript configuration needed for your app. You can split this file out if it gets too large, we will use `main.js` to import everything in at the end.
+
+You should firstly instantiate any classes/modules you need. For example you can import and create the font-awesome library, adding the icons you need.
+
+Secondly, you should `export default{}` and create key:value pairs. These values should be callback functions (arrow functions) that return the javascript needed for that partiuclar task. We go through some of these below.
+
+The purpose of `App.js` is:
+
+- Any javascript that you need across your whole project.
+
+For example if we are using Font Awesome, we will need to import it and run the javascript needed (`dom` and `library`).
+
+- Manipulating the dom (with JQuery).
+
+If we are using Hugo's markdown, it won't apply any classes to a table for stying with bootstrap. We can craete a function that adds bootstrap classes to certain tags, filling in what Hugo doesn't support:
+
+```javascript
+export default {
+  bootstrapify: () => {
+    $('.content blockquote').addClass('blockquote');
+    $('.content table').addClass('table');
+    $('.content table').wrap('<div class="table-responsive" />');
+    $('.content table thead').addClass('thead-dark');
+    $('.content pre').wrap('<figure class="highlight" />');
+    $('.content figure > img').addClass('img-fluid');
+  }
+```
+
+We can use Jquery's `addClass` and `wrap` methods to manipulate the HTML that Hugo produces.
+
+Here we are using webpack's plugins to provide jquery across everything without having to import it every time. See the webpack notes for more on what it does.
+
+Another example of this is writing a `navbarFade` function. This will hide the navbar if we scroll past a certain point:
+
+```javascript
+navbarFade: () => {
+  let $position = $(window).scrollTop();
+
+  $(window).scroll(() => {
+    const $scroll = $(window).scrollTop();
+    const $navbarHeight = $("#navbar-main-menu.fixed-top").outerHeight();
+
+    $scroll > $position
+      ? $("#navbar-main-menu.fixed-top").css("top", -$navbarHeight)
+      : $("#navbar-main-menu.fixed-top").css("top", 0);
+
+    if ($scroll <= 0) {
+      $("#navbar-main-menu.fixed-top").css("top", 0);
+    }
+
+    $position = $scroll;
+  });
+},
+```
+
+This callback function, like all the others, will be called in the `main.js` file later and be available site-wide.
+
+- Adding lazyload
+
+We can use lazyload (provided by `vanilla-lazyload`). To do this, we should create an arrow function that asynchronously imports `vanilla-lazyload` and intantiates a new `LazyLoad object`:
+
+```javascript
+lazyload: async () => {
+  const { default: LazyLoad } = await import(/* webpackChunkName: "lazyload" */ 'vanilla-lazyload');
+  new LazyLoad({
+      thresholds: "40px 10%",
+      load_delay: 100,
+  });
+},
+```
+
+Then we can use `data-src=""` in any `<img>` tags to use lazyloading.
+
+- Adding a JQuery library (ekko-lightbox)
+
+Ekko-lightbox <http://ashleydw.github.io/lightbox/> can be used to create a lightbox gallery using bootstrap.
+
+Instructions are to insert some JQuery into your site. So we can use a callback function here to do this:
+
+```javascript
+lightbox: async () => {
+  const { default: ekkoLightbox } = await import(
+    /* webpackChunkName: "ekkoLightbox" */ "ekko-lightbox"
+  );
+  $('[data-toggle="lightbox"]').click(function (e) {
+    e.preventDefault();
+    $(this).ekkoLightbox();
+  });
+},
+```
+
+Note that with JQuery:
+
+```javascript
+$(document).on('click', '[data-toggle="lightbox"]', function(e) {
+```
+
+Is functionally the same as here:
+
+```javascript
+$('[data-toggle="lightbox"]').click(function (e) {
+```
+
+because `$(document)` will wait for the DOM to be loaded before running it. As we are using a seperate function with an event to do this, we don't need to use `$(document)` and we can just use the normal JQuery syntax.
+
+##### Using a CDN (prism)
+
+It's possible to still use a CDN with webpack. You might want to do this (say when using Hugo) if you want to toggle an option in a config file, and have Hugo insert the prism CDN if present, or return nothing.
+
+It is possible when doing this to also configure the plugin locally in webpack. We can use an `if` in javascript to see if the plugin is active, and if it is return our config, else return nothing.
+
+To insert using a CDN place your `<script>` tags in the footer (at the end of the body) as usual:
+
+```html
+{{ if .Site.Params.prismJS.enable }}
+<script>
+  window.Prism = window.Prism || {};
+  window.Prism.manual = true;
+</script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/components/prism-core.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/plugins/autoloader/prism-autoloader.min.js"></script>
+{{ end }}
+```
+
+We should also add the CSS to the `head.html` as well, since we will be using a CDN for this as well:
+
+```hugo
+{{ if .Site.Params.prismJS.enable }}
+{{ if .Site.Params.prismJS.theme }}
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/themes/prism-{{ .Site.Params.prismJS.theme }}.min.css">
+{{ else }}
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/themes/prism.min.css">
+{{ end }}
+{{ end }}
+```
+
+We're following the Prism documentation: <https://prismjs.com/#basic-usage-cdn>.
+
+Because we are setting `Prism` to manual, we will need to call the api manually, this can be done in the `App.js` under a callback function:
+
+```javascript
+syntaxHighlight: () => {
+  if (!window.Prism) {
+    return;
+  }
+
+  Prism.highlightAll();
+
+  $("pre:has(> code[class*=language-])").removeAttr("style");
+
+  const element = $("pre:has(> code:not([class*=language-]))");
+
+  element.addClass("language-none");
+  $("> code", element).addClass("language-none");
+},
+```
+
+We are checking to see if the Prism object is available, if not we return nothing and no hightlighting by Prism will be done.
+
+Then we call the `highlightAll` method on the `Prism` object.
+
+Finally, since Hugo applies its own code styling by default which cannot be turned off, we apply some JQuery that removes the Hugo added style.
+
+#### main.js
+
+This should go in the root of `./src`. This will be our entrypoint into our javascript and we split this out for one main reason.
+
+In this file we should import our `styles.scss`:
+
+```javascript
+import "./scss/styles.scss";
+```
+
+We can also import any third party javascript libraries in here. `App.js` is more useful for verbose configs and custom site js. For simple imports we can place these in `main.js`:
+
+```javascript
+import(/* webpackChunkName: "bootstrap" */ "bootstrap");
+```
+
+We want to add a `window.addEventListener` that listens for `'DOMContentLoaded'` and then fires an async function. **We only need to do this if we are interacting with the DOM.** If we are using JQuery in our `./src/js` files, then we need to wait for the browser to finish rendering the DOM before interacting with it.
+
+Youtube tutorial explaining this in detail: <https://www.youtube.com/watch?v=m1DH8ljCqzo>.
+
+We might need to do this with JQuery, or even FontAwesome which has a `dom.watch()` method.
+
+Inside this function, we should import the `App` javascript file containing all our javascript:
+
+```javascript
+const { default: App } = await import(/* webpackChunkName: "app" */ "./js/App");
+```
+
+We are using `import` asynchronously to import the javascript file. We don't need the extension `.js` just like in `.scss` files.
+
+We are setting this to a const `App`. We need to import the object `default` as that is what is exported in `App.js`.
+
+Then, we can call each callback function in the `default` object which is accessible under the variable `App`:
+
+```javascript
+window.addEventListener("DOMContentLoaded", async (event) => {
+  const { default: App } = await import(
+    /* webpackChunkName: "app" */ "./js/App"
+  );
+
+  App.loadFontAwesome();
+  App.bootstrapify();
+  App.lazyload();
+  App.navbarFade();
+  App.lightbox();
+  App.syntaxHighlight();
+});
+```

blog/webpack.md

@@ -1,88 +0,0 @@
-## Webpack
-
-Great tutorial for the basics: <https://www.sitepoint.com/bundle-static-site-webpack/>.
-
-We can use webpack to bundle up our resources (javascript files or css files) and create a minified bundle for a website.
-
-You can bundle anything up, we can even write `scss` and have webpack lint, compile and minify into the `dist` directory for us automatically.
-
-### Structure
-
-#### Folder structure
-
-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.
-
-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`.
-
-### Build patterns/ code organisation
-
-#### SCSS/CSS
-
-Any scss/css you want to use should go in your raw folder.
-
-You should have a `_variables.scss` which should define and/or overwrite any variables from any frameworks you are importing (bootstrap).
-
-You can then have as many `scss` files as needed for your content. You can split them by page, or by component etc.
-
-Finally you should have a `styles.scss`. This file should import all the `scss` files you've created, in addition to any provided by third party packages. Remember to import the `_variables.scss` file first and any other `scss` files that are overwriting something else.
-
-TODO: Link to the example `styles.scss` in git.
-
-With `scss`, imports are done with the `@import "";` syntax. You leave out the extension if it's `.scss`, otherwise provide it if it's `css`.
-
-If you want to reference a file in `node_modules` you can use the `~` as a shortcut to that path. E.g `@import "~bootstrap/scss/bootstrap";`.
-
-#### Javascript
-
-You should use asynchronous imports to improve performance in your `.js` files.
-
-We create two files: `App.js` and `main.js`.
-
-##### App.js
-
-This file should go in `./src/js`. It should contain all the javascript configuration needed for your app. E.g if using font-awesome's javascript loader and library functionality you should import them and add them here.
-
-TODO: Link to the example `App.js` file in git.
-
-We go through some common options for a project (in Hugo) here.
-
-### Config
-
-`output.path` is where the bundles files will go
-is `output.publicPath` the path you will reference in the `html`. Here is a webpack wiki explanation: <https://github.com/webpack/docs/wiki/configuration#outputpublicpath>.
-
-### Use npm to install bower dependencies
-
-As `bower` is deprecated in favour of `yarn` and `webpack`, most packages now come with `npm`.`yarn`.
-
-You can use `npm` to install bower dependencies if they are old and haven't been updated for `npm`.
-
-#### Change bower installation path
-
-You should change the installation path for `bower` from `bower_modules` to `node_modules`.
-
-To do this create a `.bowerrc` file in the root of your repo that contains the following:
-
-```json
-{
-  "directory" : "node_modules"
-}
-```
-
-#### Allow npm to run bower install
-
-You can use an `npm` script to run `bower install` which will install your bower dependencies whenever you do `npm install`.
-
-Edit the `scripts` in your `package.json` to add the following:
-
-```json
-"scripts": {
-  "postinstall": "bower install"
-}
-```

hugo.md

@@ -270,7 +270,12 @@ If you want to insert an image in the html you can use the `<img>` tag directly.
 Place all images in `./static/images`, Hugo will reference these as `/images/$image`:
 
 ```html
-<img src="/images/DUCK_256.png" width="30" height="30" class="mr-3 rotate-a-20"/>
+<img
+  src="/images/DUCK_256.png"
+  width="30"
+  height="30"
+  class="mr-3 rotate-a-20"
+/>
 ```
 
 ### Working with parameters and front matter
@@ -297,7 +302,6 @@ You can set a variable to whatever the `with` block is referencing by immediatel
 
 The `-` on both sides trims any whitespace in the outputted HTML.
 
-
 ## Email
 
 ### Sending email with AWS SES
@@ -318,3 +322,37 @@ You should verify an email (or domain ) that you own with AWS: <https://docs.aws
 
 An example `docker-compose` for compose app sending emails with SES is here: <https://git.panaetius.co.uk/hugo/docker-compose/src/branch/master/blog/commento/docker-compose.yml>.
 
+## Adding a new font family with CSS
+
+To create a new font family you should create a `@font-face` in the scss. You should create multiple instances of these and specify the `font-weight` in order for the html to use the appropiate style of font.
+
+`font-face` documentation: <https://www.w3schools.com/cssref/css3_pr_font-face_rule.asp>.
+
+A table of `font-weight` and what `normal` and `black` correspond to in numbers (for css) can be found: <https://docs.microsoft.com/en-us/typography/opentype/spec/os2#usweightclass>.
+
+The default `font-weight` is `normal` and the default `font-style` is `normal`.
+
+To set an italic font you should set `font-style: italic;` in this `@font-face` for the custom italic font you want to use. Without setting this, the browser will take the weight font you are using, and apply its own slanting to it.
+
+You should apply `font-display: swap;` to make sure the browser shows text with the default system font while the custom font is loaded in.
+
+TODO: Link to `fonts.scss` in git
+
+An example of what this might look like for two styles is:
+
+```scss
+@font-face {
+  font-family: "RNSSanz";
+  src: url("../../static/fonts/RNSSanz-Light.ttf");
+  font-weight: 300;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: "RNSSanz";
+  src: url("../../static/fonts/RNSSanz-Normal.ttf");
+  font-display: swap;
+}
+```
+
+Then in your other `scss` files you can refer to this with `font-family: "RNSSanz` along with any of the `font-weight` you have defined.

tasks.todo

@@ -99,6 +99,7 @@ Tasks:
     ☐ Find simple CSS design for search bar.
     ✔ Implement search using a library. @done (5/13/2020, 1:57:50 AM)
     ✔ Search needs to recusrively go into folders @done (5/12/2020, 3:36:52 AM)
+    ☐ Document using and creating a search page with lunrjs. (use the temporary search note).
     Links:
       - https://codewithhugo.com/hugo-lunrjs-search-index/
       - https://gist.github.com/HugoDF/aac2e529f79cf90d2050d7183571684b