Site

This repository contains the public website at bcm.works, along with related assets and documentation.

Status

Structure

• .claude - Project specific config for Claude Code.
• .mise - Project specific config and commands using Mise.
• .zed - Customised Zed Editor project configuration.
• content - Website page content in Markdown files.
• design - Page layout and icon design files.
• docs - Documentation and contextual information.
• docs/adrs - Architecture decision records in Markdown files.
• docs/AI-USE.md - Policy for use of AI Code Generation tools.
• infra - Infrastructure as Code for Railway.
• prototypes - Ideas and half-built prototypes.
• src - Frontend Lume templates and backend Deno static file server.
• src/pwa-manifest.json - Progressive Web App configuration.
• .aspens.json - Project config for Aspens
• .editorconfig - Sets basic code style rules via EditorConfig
• deno.jsonc - Deno imports, tasks and configuration.
• Dockerfile - Docker container image used for deployments.
• markdown-lint.yml - Configuration for MarkdownLint.

Tech Stack

• Railway - Infrastructure host, managed as code in infra.
• PostHog - Site analytics and visitor usage insights.
• Docker - Local and deployed containers.
• Deno - TypeScript, Deno Tests, Deno Tasks.
• Lume - Static site generator for Deno.
• Fonts by Mass-Driver - I have purchased licenses for use here.
• Font Awesome free icon pack - Used for icons on various pages and layouts.

Local Setup

The systems in this repository assume that your local machine:

• Is running a Debian-based Linux OS
• Has an up-to-date version of Mise installed and ready
• Has an up-to-date version of Homebrew installed and ready
• Has an up-to-date version of Docker CLI installed and ready

Note that my dotfiles repository contains install scripts for most of the above items.

Local Tools

Run the Mise setup task to setup your local environment:

mise run setup

This repository uses Mise to apply config and run commands from the .mise directory.

Some command aliases are set in .mise/config.toml that are available in terminal sessions in this directory after running the setup-tools command above.

To list all of the available tasks, run the alias command:

tasks

Initial Setup

1. Fork this repository
2. Make a local clone of that forked repository, apply the below updates
3. Install the latest stable release of Deno
4. Run the setup script: deno task setup
5. Update GitHub repository references in the files to use your forked GitHub repository URL instead
6. All files in the content directory must contain your own content instead
7. All files in the assets directory must contain your own static files instead
8. Purchase your own license to use the Mass-Driver IO font or update the CSS to use other fonts
9. Commit and push all of these changes to your forked repository
10. Setup your local development environment by copying .site.local.env to .site.env and then update .site.env to match your site
11. Setup your GitHub Actions Secrets by following the steps in .site.github.env
12. Setup online infrastructure via Railway by folllowing directions in src/infra

Usage

• deno task setup: Local environment setup.
• deno task build: Build the site and organise the required assets.
• deno task start: Start a local web server.
• deno task test: Run all Deno Test scripts in the 'src' directory.
• deno task install: Install third-party dependencies.
• deno task update: Update third-party dependencies.
• deno task clean: Run code cleanup tools.
• deno task lume: Run a Lume command.
• deno task new-post: Generate a Markdown file for a new post item.
• deno task docker-build: Run the Docker Image build process.
• deno task docker-start: Start the Docker Container.
• deno task docker-stop: Stop the Docker Container.

Deployment

Releases can be manually triggered from GitHub Actions via release.yml.

This script includes a push to this project's Docker Repository, which will trigger Railway to update the environment automatically.