diff --git a/v4/README.md b/v4/README.md index d513c3e5d..c0e79f411 100644 --- a/v4/README.md +++ b/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). ---- diff --git a/v4/package.json b/v4/package.json index 637795280..a3b779102 100644 --- a/v4/package.json +++ b/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", diff --git a/v4/scripts/build-example-site.sh b/v4/scripts/build-example-site.sh new file mode 100755 index 000000000..d0c15c045 --- /dev/null +++ b/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 diff --git a/v4/scripts/example-site.sh b/v4/scripts/example-site.sh deleted file mode 100755 index 1acf545be..000000000 --- a/v4/scripts/example-site.sh +++ /dev/null @@ -1,35 +0,0 @@ -#!/usr/bin/env bash - -clear - -echo -echo "----------------------------------------------------------------------------" -echo "This script starts the example site" -echo "----------------------------------------------------------------------------" - - -echo ">>> Creating example site..." - -if [ -d "tests/local" ] - then rm -rf tests/local -fi - -mkdir tests/local -cd tests/local -hugo new site my-new-blog -rm my-new-blog/archetypes/default.md -cp -r ../../exampleSite/* my-new-blog - -echo ">>> Updating 'config.toml'..." - -sed -i "s/title = .*$/title = \"Dev Bilberry Test\"/" my-new-blog/config.toml -sed -i "s/subtitle = .*$/subtitle = \"Running locally!\"/" my-new-blog/config.toml -sed -i "s/theme = .*$/theme = \"..\/..\/..\/..\/..\/v4\"/" my-new-blog/config.toml - -echo ">>> Starting Hugo server..." - -cd my-new-blog -hugo server --buildDrafts --buildFuture - -echo ">>> ... completed." -exit 0 diff --git a/v4/scripts/serve-example-site.sh b/v4/scripts/serve-example-site.sh new file mode 100755 index 000000000..78e762085 --- /dev/null +++ b/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 diff --git a/v4/scripts/setup-example-site.sh b/v4/scripts/setup-example-site.sh new file mode 100755 index 000000000..aeac3a36a --- /dev/null +++ b/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 diff --git a/v4/scripts/node-deps.sh b/v4/scripts/update-node-deps.sh similarity index 100% rename from v4/scripts/node-deps.sh rename to v4/scripts/update-node-deps.sh diff --git a/v4/v4-developer-guide.md b/v4/v4-developer-guide.md new file mode 100644 index 000000000..ff7abe8c8 --- /dev/null +++ b/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. diff --git a/v4-migration-guide.md b/v4/v4-migration-guide.md similarity index 91% rename from v4-migration-guide.md rename to v4/v4-migration-guide.md index 3697cb18d..c91b097ba 100644 --- a/v4-migration-guide.md +++ b/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