feat(v4) add developer scripts and guide (#585)

v4/README.md

@@ -13,7 +13,9 @@
 This guide is for `v4` version. For `v3`, please use this [guide](../v3-README.md).
 
 **IMPORTANT** `v3` will be supported until **August 31, 2024**. Only critical bugs will be fixed during this period, no
-new features will be implemented.
+new features will be implemented. If you want to migrate from `v3` to `v4`, please read the migration [guide](v4-migration-guide.md).
+
+For those who want to contribute to or customize the Bilberry Hugo theme, please see the developer [guide](v4-developer-guide.md).
 
 ----
 

v4/package.json

@@ -24,10 +24,10 @@
     "vue-template-compiler": "^2.6.11"
   },
   "scripts": {
-    "deps": "./scripts/node-deps.sh",
-    "build": "rm -rf public ; hugo",
-    "example": "./scripts/example-site.sh",
-    "stop": "killall hugo"
+    "update-deps": "scripts/update-node-deps.sh",
+    "build-example": "scripts/build-example-site.sh",
+    "serve-example": "scripts/serve-example-site.sh",
+    "stop-hugo": "killall hugo"
   },
   "repository": {
     "type": "git",

v4/scripts/build-example-site.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+clear
+
+echo
+echo "----------------------------------------------------------------------------"
+echo "This script set ups and builds the example site"
+echo "----------------------------------------------------------------------------"
+
+./scripts/setup-example-site.sh
+
+echo ">>> Building example site..."
+
+cd tests/local/exampleSite || return
+hugo --environment development --buildDrafts --buildFuture
+
+echo ">>> ... completed."
+exit 0

v4/scripts/serve-example-site.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+clear
+
+echo
+echo "----------------------------------------------------------------------------"
+echo "This script set ups and serve the example site"
+echo "----------------------------------------------------------------------------"
+
+./scripts/setup-example-site.sh
+
+echo ">>> Starting Hugo server..."
+
+cd tests/local/exampleSite || return
+hugo server --buildDrafts --buildFuture
+
+echo ">>> ... completed."
+exit 0

v4/scripts/setup-example-site.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+clear
+
+echo
+echo "----------------------------------------------------------------------------"
+echo "This script set ups the example site"
+echo "----------------------------------------------------------------------------"
+
+echo ">>> Setting up example site..."
+
+if [ -d "tests/local" ]
+  then rm -rf tests/local
+fi
+
+mkdir tests/local
+cd tests/local || return
+hugo new site exampleSite
+rm exampleSite/archetypes/default.md
+cp -r ../../exampleSite/* exampleSite
+
+echo ">>> Updating 'config.toml'..."
+
+sed -i "s/title = .*$/title = \"Dev Bilberry Test\"/" exampleSite/config.toml
+sed -i "s/subtitle = .*$/subtitle = \"Running locally!\"/" exampleSite/config.toml
+sed -i "s/theme = .*$/theme = \"..\/..\/..\/..\/..\/v4\"/" exampleSite/config.toml
+
+echo ">>> ... completed."
+exit 0

v4/v4-developer-guide.md

@@ -0,0 +1,39 @@
+## v4 Developer Guide
+
+### Prerequisites
+- **Hugo** (version >= 0.109.0 **extended**), see this installation [guide](https://gohugo.io/getting-started/installing/).
+- **Git**, see this installation [guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+- **Go** (version >= 1.19), see this installation [guide](https://go.dev/doc/install).
+- **Node.js** (version >= 20.5.0) with **npm** (version >= 9.8.0), see this
+  installation [guide](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
+### Third-party Dependencies
+
+Third-party dependencies are managed using `npm` and listed in
+the [`devDependencies`](https://github.com/Lednerb/bilberry-hugo-theme/blob/3776287f2e4494c1308593bde531dbe944de6ddd/v4/package.json#L6)
+block of `package.json` file.
+
+* To update dependencies, adjust version numbers in the `devDependencies` bloc and execute the following command from
+  project's `v4` folder:
+
+  ```bash
+  $ npm run update-dep 
+  ```
+
+* To add a new dependency, add it to the `devDependencies` bloc and execute the `npm run update-dep` command. Then,
+  examine the location of the new dependency's CSS and JavaScript files in the `v4/node_modules` folder. Dependencies,
+  namely CSS and JavaScript artifacts must be copied from the `v4/node_modules` folder to the `v4/assets/sass/_vendor`
+  and `v4/assets/js/_vendor` folders, respectively. Therefore, update the `v4/scripts/update-node-deps.sh` script and
+  execute the `npm run update-dep` command again. For the newly copied SCSS and JavaScript artifacts to be used by Hugo
+  pipes, they should be included in the `v4/assets/sass/theme.scss` and `v4/layouts/partials/js.html` files. Therefore,
+  update these files accordingly, and commit the changes.
+
+### Example Site
+
+* To build the example site, execute the `npm run build-example` command. Then, examine the content of
+  the `v4/tests/local/exampleSite/public` folder.
+
+* To run the example site, execute the `npm run serve-example` command. The example site will be available
+  at http://localhost:1313/.
+
+* To stop all instances of the Hugo server running in your local dev, you may use the `npm run stop-hugo` command.

v4-migration-guide.md → v4/v4-migration-guide.md

@@ -26,7 +26,7 @@ theme = "bilberry-hugo-theme/v4"
 ### Syntax Highlighting
 
 No modifications are needed for posts with any existing code blocks. Syntax highlighting will work the same way as with
-the `v3` version. Please see the [Syntax Highlighting](v4/README.md#syntax-highlighting) section in the `v4` **README** 
+the `v3` version. Please see the [Syntax Highlighting](README.md#syntax-highlighting) section in the `v4` **README** 
 guide for customization options.
 
 ### Color and Font Customizations
@@ -35,7 +35,7 @@ In `v3`, color and font customizations were handled directly in the `assets/sass
 the `_variables.scss` file no longer exists and such customization is done in the `config.toml` by defining
 corresponding parameters from the `assets/sass/theme.scss` file, for example, `baseColor`, `headlineFont` etc.
 Therefore, any changes you made in `_variables.scss` file should be ported to your site's configuration file. Read
-the [Colors and Fonts](v4/README.md#colors-and-fonts) section in the `v4` **README** guide for more details.
+the [Colors and Fonts](README.md#colors-and-fonts) section in the `v4` **README** guide for more details.
 
 ### Image Modal Zoom