Project Mackenzii

This repo holds the various projects associated with @goldenwere/mackenzii, a template-based static site generator aimed at splitting dynamic site content from fixed site code.

Local Development

These instructions will try to be as thorough as possible and/or link to necessary references as much as possible in order for those who may not be used to this sort of development environment.

Git

While you could simply download the source code directly and work with it without git, it would be easier to pull updates to mackenzii by installing git on your machine. When git is installed, open a terminal and enter the command git clone <repo url> <directory to clone to>, e.g. git clone https://git.goldenwere.com/Goldenwere/mackenzii.git /home/me/mackenzii.

Node / NPM

Make sure you have node installed on your machine. The best way to manage node is to use nvm (windows version). This project uses .nvmrc to inform nvm of the targeted (ideal) version to use. Running nvm install {version-in-nvmrc} will install the appropriate version, and running nvm use in every terminal session will keep node in sync with .nvmrc (if the version is not installed, nvm will tell you what version to install). Once node is installed, run npm ci in a terminal to install the dependencies used by the project.

Managing content

At the minimum, you will need at least one site directory under /projects/manager/sites/<my-site-name> with a config.json file with the required fields set at the root of that directory in order to preview and build your site(s). Run npm run set-current -w=manager --site=<my-site-name>, where <my-site-name> matches the name of the folder in /projects/manager/sites, in order to set the site you are currently working with. You can have multiple sites in this directory and swap between them with npm run set-current.

Live Preview

You can run npm start in the terminal to spin up a server. Open the address shown the terminal in your browser to preview what your site looks like. It has hot reloading, which means you can make changes to site code and certain files that will be instantly reflected on the page you have open. Some more core files may cause the page to fully reload, while some simple changes like stylesheet/component changes may be reflected without full reloading. Note that fetched content (page markdown/config files) is not caught by hot reload, so you will need to reload manually in those cases.

Building

Running npm run build will build out the project. Be sure that you had previously set npm run set-current -w=manager --site=<site-name> before building so that the site builder can build from config.json. When the build command is executed, vite-ssg will build the frontend into the /projects/frontend/dist folder. The build process will ensure that the previously set site is copied into the generated dist directory. The dist directory contains your static site's files. Note that if you run npm run set-current after a build with a different site from that build, you should re-run npm run build as well.