ngxv.org

Introduction

This repository contains the source code of ngxv.org. The development started with node.js/npm but was migrated to deno because I see deno environment is better in terms of consistency, dependency management.

ngxv.org is a small website for my home page and blog. On the home page, I listed the company that I worked and some stuffs I did over the years. The blog contains my writings about the things I'm interesting and what I believe.

Requirements Overview

Features

• Home page: short introduction about the author, stuffs he created, companies he worked.
• Blog: the author's writings about the things he's interesting and what he believes. Reader could read the blog in chronological order or filter by tags.
• Atom feed: user with feed reader could subscribe easily.

Non-Functional Requirements

• Lightweight: the website should be minimal, it works best on modern browser but also works when JavaScript is disabled.
• Secure: the website is pre-generated, no backend needed.
• The blog entry is written in Markdown, it supports image.
• Store all code dependencies to <repo-root>/vendor to less depend on outside source.

Architecture Constraints

Technical Constraints

• Programming language: JavaScript, HTML, SCSS, Bash script.
• Platform: deno 2.0.4 or later.
• Framework: preact 10.20.1.
• IDE: IntelliJ IDEA 2023 or later.
• Source version control: git, GitHub.
• Development tools.
  • bash/zsh: run various scripts during development.
  • git: source version control and release.
  • deno 2.0.4 or later: code format, bundle, run generator...
  • dart-sass 1.57 or later: build SCSS.
• Development environment: macOS.
• Production environment: OpenBSD, httpd, relayd.

Conventions

• Architecture documentation: arc42.

System Scope and Context

Business Context

• User: a person who visits the website.
• Author: the person who created the website's source code and its content.

Technical Context

(to be updated: draw a diagram to visualize the deployment)

Solution Strategy

(to be defined)

Building Block View

(to be defined)

Runtime View

(to be defined)

Deployment View

(to be defined)

Concepts

(to be defined)

Todo

• Use CSS variables for style so that we can adapt the style sometime.

Git workflow

Branch convention

trunk contains released code.

feature/<name-of-feature> contains current developing feature. The branch is derived from trunk and to be merged to trunk. We should maintain the linear history of trunk.

draft/<name-of-blog-entry> contains draft blog entry. The branch is derived from trunk. We can publish the entry by merging the branch to trunk with rebase strategy.

gh-pages contains generated website, we didn't use GitHub Page since March 2023 and moved to self-hosted server, we keep the branch name for historical reason. The branch is created by command <repo-root>/script/publish.

Develop new feature

1. Create new feature/* from trunk.
2. Develop feature.
3. Test and merge to trunk with rebase strategy.

Write blog entry

1. Create new draft/* from trunk.
2. Write blog entry.
3. Test and merge to trunk with rebase strategy.

Building the website

On the development machine, run the following command to build the website:

<repo-root>/script/build-web-prod

Publishing the website

<repo-root>/script/publish

The static files are generated and saved to branch gh-pages.

Login to the server, clone the repository (skip if already cloned).

git clone git@github.com:cavoirom/nxv.git

Run the deploy script to publish the website.

<repo-root>/script/httpd-deploy

Design Decisions

• We will stop wouter-preact at 2.x version, because the newer version is becoming bloated.

Troubleshooting

Error when generating the website (preact 10.16.0): Uncaught TypeError: Cannot read properties of undefined (reading '__H')

It's because of multiple versions of preact are used. The solution is defining the same preact version all dependencies.

Reference: preactjs/preact#3657 (comment)

Quality Requirements

• Have at least one test case for each component.

Risks and Technical Debts

(to be defined)

Glossary

(to be defined)