Skip to content
This repository has been archived by the owner on Dec 4, 2024. It is now read-only.

Latest commit

 

History

History
446 lines (377 loc) · 31 KB

DEV-WIKI.md

File metadata and controls

446 lines (377 loc) · 31 KB

Table of contents

🔍Developer Wiki

This bare-bones wiki contains information for developers working on the site. If you are not sure how something works, please don't hesitate to ask!

Tip

You can use the glossary to understand the terms used in this wiki.

To get yourself familiarised, you are recommended to follow one of the tracks depending on what you are trying to do.

I just want to write content wtf is this:

  1. Shortcut
  2. Getting started
  3. Testing the site
  4. Committing changes
  5. Writing content for the site

I am just getting started:

  1. Getting started
  2. Testing the site
  3. Committing changes
  4. Understanding the repository structure

I want to work on the frontend:

  1. Understanding the repository structure
  2. Understanding the framework
  3. Working on the frontend

I want to work on the framework:

  1. Understanding the repository structure
  2. Understanding the framework
  3. Working on the framework

❓Getting started

Install VSCode

  1. Install VSCode from https://code.visualstudio.com/ following the default installation instructions

Install Git

  1. Install Git from https://git-scm.com/ following the default installation instructions

Install Node.js via NVM

  1. Download and run nvm-setup.exe NVM from https://github.com/coreybutler/nvm-windows/releases following default installation instructions
  2. Launch VSCode
  3. Open the terminal with Ctrl + ` (backtick)
  4. Run nvm list available to see the available versions of Node.js, remember the latest LTS version number (e.g. 20.15.0)
  5. Run nvm install <LTS Version> to install the latest LTS version of Node.js (e.g. nvm install 20.15.0)
  6. Run nvm use <LTS Version> to switch to the installed version of Node.js (e.g. nvm use 20.15.0)
  7. Run node --version to check that Node.js has been installed correctly, you should see the version number

Install recommended VSCode extensions

  1. Open the extensions sidebar with Ctrl + Shift + X
  2. Search for @recommended and install all the recommended extensions

Clone the repository

  1. In file explorer, create a new folder for the repository and navigate into it
  2. Right-click and select Open with Code to open the folder in VSCode
  3. Open the terminal with Ctrl + ` (backtick)
  4. Run git clone https://github.com/ResiSense/ResiSense.github.io.git to clone the repository
  5. Close VSCode
  6. In file explorer, navigate to the cloned repository folder ResiSense.github.io
  7. Right-click the folder and select Open with Code to open the repository in VSCode
  8. Open the terminal with Ctrl + ` (backtick)
  9. Run npm install to install the required dependencies

🧪Testing the site

  1. Open the terminal with Ctrl + ` (backtick)
  2. Run npm run dev to build the site for testing, you should find a new test folder in the repository
    • For frequent testing, you can run npm run watch to automatically rebuild the site on changes not in .gitignore
      • npm run dev is automatically run under the hood
  3. In file explorer, navigate to the test folder
  4. Right-click the folder and select Open with Code to open the test site in another VSCode window
  5. Open the command palette with Ctrl + Shift + P
  6. Search for Live Server: Open with Live Server and select it to open the test site in your browser

The test site should now be running in your browser.

Note

Navigating to .../<page> does not automatically serve .../<page>.html and you will see an error. Please manually append .html to the URL. This issue only affect the test site and not the live site.

Live reloading should be enabled so that changes to the source code are automatically reflected in the browser after running npm run dev. You can also refresh manually if live reloading fails.

Tip

The test folder is not tracked by Git and can be deleted or modified at any time without consequence. Feel free to use it as a sandbox to test stuff with!

✍🏻Committing changes

  1. You are recommended to read up on the basics of Git and GitHub if you are not familiar with them
  2. Open the source control sidebar with Ctrl + Shift + G
  3. Sign in to your GitHub account as necessary, make sure your account is in the website team
  4. At the bottom left corner of VSCode, check to make sure you are checking out to the correct branch (don't commit to main directly!)
    • To create a new branch:
      1. If you have already made changes, stash them by selecting Stash > Stash (Include Untracked) under the ... menu
      2. Under the ... menu, select Branch > Create new branch and name the branch after the changes you are making
      3. Click Publish
      4. If you have stashed changes, retrieve them back by selecting Stash > Pop Stash under the ... menu
    • To checkout to an existing branch:
      1. Under the ... menu, select Checkout to... and select the branch you want to checkout to
  5. Stage the changes by clicking the + button next to each file name
  6. Write a commit message in the text box at the top of the sidebar to describe the changes
    • You are recommended to make a new commit by each change or feature you are making
      • ❌ Don't do this:
        • One commit for everything you have changed (e.g. add new page & update styles & fix bugs)
        • Commit messages that are too vague (e.g. update stuff)
      • ✔️ Do this:
        • One commit for one feature (e.g. add responsive scrolling)
        • One commit for one bug fix (e.g. fix page not updating)
        • Group changes to multiple files in one commit if they are related (e.g. update page content)
        • Put a minor: prefix if you are only fixing typos or something (e.g. minor: fix typo)
    • If you can't describe the changes clearly and concisely, you are probably doing too much in one commit
  7. Click Commit & Create Pull Request; you can find this button under the dropdown menu next to the commit button if it is not already visible
  8. Follow the instructions in the new browser window to create a pull request
  9. Wait for the pull request to be reviewed and merged by the repository owner (or do it yourself ¯\_(ツ)_/¯)

Feel free to make changes here as a test if you wish. (This file is /DEV-WIKI.md btw.)

Sign here if you read this:
- CCheukKa was here.
- The most important things in the world are Ka and sleep (by Tommy.2024)
- Coming in the final 5 hrs before wiki freeze (Ricky, 2024)

Post-commit CI

After committing onto GitHub, a CI pipeline as defined in .github/workflows/full-ci-pipeline.yaml is run automatically.
This usually takes ~30 seconds.

  • The site is automatically built and deployed to GitHub Pages
  • The site is automatically cloned and committed to GitLab

After auto-committing onto GitLab, a CI workflow as defined in .gitlab-ci.yml is run automatically.
This usually takes >3 minutes.

Note

Concurrent CI runs will automatically kill all old jobs. Only the most recent job will execute.

github-context.json

This context file includes a lot of information about the most recent commit, grabbed from the GitHub context object during the CI pipeline runs. Its main use is to determine which commit the deploy was built on at a glance.

The context file can be found at /github-context.json in both mirrors.

📂Understanding the repository structure

Folder Description Content Remarks
test/ Test build of the site Sandbox for testing; untracked
pages/ Content of the site .md and .html files
assets/ Assets used in the site predominantly images is cloned to docs/
scripts/ JS scripts to be packaged to clients .ts files is compiled to docs/
styles/ CSS stylesheets to be packaged to clients .css files is cloned to docs/
meta/ Metadata for the site
templates/ HTML templates for the site .html files
lib/ Framework code .ts files
lib/framework-lib/ Framework dependencies .ts files
lib/types/ Framework type and class declarations .ts files
lib/page-scripts/ Page-specific dependencies .ts files
lib/template-scripts/ Template-specific dependencies .ts files
.github/ GitHub essential files templates and actions edit with caution
.gitlab/ GitLab essential files (for Jekyll) configs edit with caution
docs/ Production build of the site DO NOT TOUCH
Important files What's this? Remarks
README.md Repository information
DEV-WIKI.md Developer wiki
TODO.md To-do list Try to keep it updated
meta/pageConfig.jsonc Metadata for pages; VERY IMPORTANT! See this
siteBuilder.ts Framework code entry point
watcher.ts Watcher code entry point for watch
boiler-plate.html Boilerplate HTML template for site builders
redirect.html Redirect HTML template page for aliases DO NOT TOUCH
.gitignore Files and folders to be ignored by Git edit with caution
tsconfig.json TypeScript configuration edit with caution
package.json Node.js package configuration edit with caution
package-lock.json Node.js dependencies edit with caution
.gitlab-ci.yml GitLab CI/CD actions (GitLab Pages deployment) edit with caution

🧠Understanding the framework

This is a very stripped-down and very custom framework specifically designed for the ResiSense website.
The framework is how the site is built and how the content is displayed.

Tip

You can refer to the glossary as necessary.

🚲Life cycle of a build

  1. siteBuilder.ts is run, via npm run dev (manual testing) or npm run prod (auto on push)
  2. assets/ and styles/ are copied to docs/
  3. The templates in templates/ are compiled recursively and cached
  4. For each page described in meta/pageConfig.jsonc:
    1. Templates are embedded into boiler-plate.html as necessary
      • CSS, JS, and TS are pushed into an array as required by the template
      • This step is referred to as template painting
    2. CSS and JS/TS are embedded into the HTML (relationally) as required by pageConfig.jsonc and the templates
    3. Post-paint TS functions are run as required by pageConfig.jsonc and the templates
    4. Page is filled with content using a populator function as described in pageConfig.jsonc
    5. Post-population TS functions are run as required by pageConfig.jsonc and the templates
    6. TS includes are run as required by pageConfig.jsonc
    7. The final HTML is written to docs/ as <page>.html
  5. JS and TS scripts in scripts/ are bundled and minified and copied to docs/
  6. The docs/ or test/ folder is now a static build of the site

Naming conventions

Type Naming convention Remarks
Templates lowercase letters only; - for spaces Name after the page
CSS embeds lowercase letters only; - for spaces Name after the template
TS embeds lowercase letters only; - for spaces Name after the template
Markdown files lowercase letters only; - for spaces Name after the page
TypeScript type declaration files PascalCase
TypeScript files camelCase
Post-paint TS camelCase Start with a verb
Post-population TS camelCase Start with a verb
TS includes camelCase Start with a verb

📝Writing content for the site

Choosing a populator is the first step to writing content for the site.

Populator Flavour 🕳️ Seamlessness 🤏🏻 Control ⏳ Speed 👶🏻 Ease
Markdown Seamless 🟢 High 🔴 Low 🟢 High 🟢 High
HTML frame Flair 🟡 Medium 🟡 Medium 🟡 Medium 🔴 Low
HTML full Control 🔴 Low 🟢 High 🔴 Low 🔴 Low

Adding a new page

Using the markdown populator

The markdown populator allows you to write content in markdown format and have it displayed on the site in the content field.

Tip

You are recommended to read up on the basics of markdown if you are not familiar with it, or use the markdown cheat sheet; it is really very simple

  1. Create a new .md file in the pages/ folder, see #naming-conventions
    • If your page is nested under another page (i.e. parent/child), create a folder parent and put child.md file in it
  2. Write your content in markdown format
    • Anything is fine really, but try not to skip heading levels (e.g. # to ###) since I believe it breaks the parser or something
  3. If you wish to use custom scripts or styles, create a new .js or .css file in the scripts/ or styles/ folder respectively; it is recommended that the scripts and styles are named after the page name
  4. Update pageConfig.jsonc to include the new page
  5. Test the site to ensure that the changes are displayed correctly (not really necessary for simple content changes)
  6. Commit the changes to the repository

Using the HTML frame populator

The HTML frame populator allows you to write content in HTML format and have it displayed on the site in the content field.

  1. Create a new .html file in the pages/ folder, see #naming-conventions
    • If your page is nested under another page (i.e. parent/child), create a folder parent and put child.html file in it
  2. Write your content in HTML format
    • You can use all the features of HTML and templates
  3. If you wish to use custom scripts or styles, create a new .js or .css file in the scripts/ or styles/ folder respectively; it is recommended that the scripts and styles are named after the page name
  4. Update pageConfig.jsonc to include the new page
  5. Test the site to ensure that the changes are displayed correctly
  6. Commit the changes to the repository

Using the HTML full replacer

The HTML full replacer allows you to replace the entire content of a page with an HTML file.

  1. Create a new .html file in the pages/ folder, see #naming-conventions
    • If your page is nested under another page (i.e. parent/child), create a folder parent and put child.html file in it
  2. Write your content in HTML format
    • Your file should be a full HTML document, including the <html>, <head>, and <body> tags
    • You can use all the features of HTML and templates
  3. If you wish to use custom scripts or styles, create a new .ts or .css file in the scripts/ or styles/ folder respectively; it is recommended that the scripts and styles are named after the page name
  4. Update pageConfig.jsonc to include the new page
  5. Test the site to ensure that the changes are displayed correctly
  6. Commit the changes to the repository

Making changes to an existing page

  1. Open the file and make the necessary changes
  2. If you have made new custom scripts or styles, update pageConfig.jsonc
  3. Test the site to ensure that the changes are displayed correctly (not really necessary for simple content changes)
  4. Commit the changes to the repository

Updating pageConfig.jsonc

See meta/pageConfig.jsonc for more information.

Adding a new entry

Tip

Copy-and-pasting is your friend!

  1. Add a new entry(/object) to the pages array in pageConfig.jsonc
    • Note that the order of the entries determine the order of the pages shown on the site catalogue
  2. Change the name field to the name of the .md/.html file in pages/ without the extension (e.g. example.md -> example); this must match the file name exactly
    • If your page is nested under another page (i.e. parent/child):
      • Under the parent entry, add a pages array and add the new page object to it
      • Use child as the name
  3. Change the title field to the title of the page as you want it to appear on the site; this is not necessary if the title is the same as the name
    • If unset, the name, capitalised, will be used as the title
  4. Change the populator field to markdown/html-full/html-frame to use the appropriate populator
  5. If you are using custom scripts or styles, add them to the scripts and styles arrays respectively; it is recommended that the scripts and styles are named after the page name
  6. If you want to add an alias for the page, add it to the redirectAliasPaths array; be careful of path collisions!

Shortcut for lazies

I recommend you to go through the steps above to understand how the site works. But still here's a shortcut if you are lazy and don't want to go through #getting-started.
You can just get a file and upload/dump it here and I will take care of the rest. Use the ResiSense GitHub account to do this maybe despite it normally being a terrible idea.

✨Working on the frontend

Tip

Copy-and-pasting is your friend!

The frontend primarily makes use of templates, CSS embeds, JS embeds, and TS embeds to structure the site. Your domain should mainly be templates/, styles/, and scripts/. Make sure you understand the repository structure.
Test the site after making changes to ensure that they are displayed correctly.

🖼️Working on the framework

If you are working on the framework, you are probably comfortable enough to know what you are doing. siteBuilder.ts is the entry point of the framework. Good luck!

PageData

Definition
PageData is a TypeScript type that is passed to internal builder functions, post-paint TS, post-population TS, and TS includes, in this order.
Variables can be attached onto this type to be passed down these functions.

📖Glossary

Content

Content is defined as the main place for content in a page, conventionally the <paintable-content />.

Content population

Content population is the process of filling the content of a page with a populator function.

CSS embeds

CSS embeds are CSS files that are embedded into the HTML relationally as <link> tags.
Tags that reference templates should use the painted tag name.

HTML frame populator

The HTML frame populator is a function that fills the content of a page with an HTML file during content population.
It is recommended to read the comments in the file itself to understand how it works.

HTML full replacer

The HTML full replacer is a function that replaces the entire content of a page with an HTML file during content population.
It is recommended to read the comments in the file itself to understand how it works.

JS embeds

JS embeds are external JS scripts that are embedded into the HTML relationally as a <script> tag.
Only use them to refer to external scripts.

Markdown populator

The markdown populator is a function that fills the content of a page with a markdown file during content population.
It is recommended to read the comments in the file itself to understand how it works.

pageConfig.jsonc

This file is probably the most important file in the repository. It describes the structure of the site and how the content is displayed.
In short, it is a JSON file that describes the metadata of each page on the site. It is required to edit this file to add new pages or change existing ones.
It is recommended to read the comments in the file itself to understand how it works. You can also refer to updating pageConfig.jsonc for more information.

Populator

Populators are functions that fill the content of a page. They are called by the framework to fill the content of a page.

It is recommended to read the comments in the files themselves to understand how it works.

Post-paint TS

Post-paint TS is the TS that is run after painting all templates.
Only the default exported function is run, with PageData passed as the only argument.
Variables that reference templates should use the painted tag name.
CSS embeds are NOT in scope.

Post-population TS

Post-population TS is the TS that is run after populating the content of a page. Only the default exported function is run, with PageData passed as the only argument.
Variables that reference templates should use the painted tag name.
CSS embeds are NOT in scope.

Template

A template is a partial HTML file that is embedded/painted into the boilerplate HTML or another template.
Templates can recursively require CSS, JS, TS, and other templates in them with the following tags:

  • <custom-example />: Paints a templates/example.html template
  • <ts-post-paint src="/lib/template-scripts/example.ts" />: Runs lib/template-scripts/example.ts after painting
  • <ts-post-population src="/lib/template-scripts/example.ts" />: Runs lib/template-scripts/example.ts after populating the content
  • <ts-embed src="/scripts/example.ts" />: Embeds scripts/example.ts as a TS embed
  • <js-embed src="https://.../example.js" />: Embeds https://.../example.js as a JS embed
  • <css-embed href="/styles/example.css" />: Embeds styles/example.css as a CSS embed

Note that the exact syntax of these tags must be followed for the framework to work correctly. Change only example to the name of the file.

A painted template will have its tag replaced from <custom-example /> to <painted-example> </painted-example> with the content of the template within.

Template compilation

Template compilation is the process of recursively compiling templates.

Template painting

Template painting is the process of embedding templates into the boilerplate HTML.
CSS, JS, and TS files are also pushed into arrays as required by the template.

TS embeds

TS embeds are TS scripts that are transpiled back to JS and embedded into the HTML relationally as a <script> tag.
Variables that reference templates should use the painted tag name.
CSS embeds are in scope.
Writing TS embeds in plain JS is also fine but discouraged.

TS includes

TS includes are the TS files that are run after post-population TS.
Only the default exported function is run, with PageData passed as the only argument.
Variables that reference templates should use the painted tag name.
CSS embeds are NOT in scope.