Terence Kong Portfolio

This repository contains the source for Terence Kong's personal site, built with Docusaurus. It combines an interactive landing page, a searchable documentation hub, a portfolio that blends curated client work with live GitHub data, and a developer blog.

Overview

• The home page introduces Terence with a typewriter-style role rotation and highlights his journey into software engineering. The layout is implemented in src/pages/index.tsx and reuses shared components such as src/components/HomepageFeatures for storytelling content and illustrations.
• A dedicated portfolio page reads professional engagements from src/data/professionalProjects.json and optionally augments them with the latest starred GitHub repositories generated by scripts/build-portfolio.ts. Visitors can filter projects by technology directly on the page (src/pages/portfolio/index.tsx).
• Documentation and long-form notes live under the docs/ directory and are enriched with remote Markdown pulled from external repositories that are listed in scripts/remoteSources.ts. These external notes are downloaded at build time through the helper scripts in scripts/, ensuring the site always ships with the latest copies.
• The blog section under blog/ captures detailed walkthroughs, complete with images, such as the Cypress visual testing guide. Docusaurus' classic preset handles author metadata, feeds, and reading-time estimates through docusaurus.config.ts.

Together, these pieces present a single destination where recruiters or collaborators can review Terence's background, browse working examples, and dig deeper into his technical writing.

Key Features

Automated content aggregation

• scripts/generate-remote-docs.ts inspects the repositories declared in scripts/remoteSources.ts, detects Markdown or MDX files, and produces a plugin manifest so Docusaurus can mount them as local docs.
• scripts/import-remote-docs.ts, scripts/fetch-remote-images.ts, and scripts/repair-remote-markdown.ts work in tandem to download those remote documents, pull any relative images they reference, and escape problematic MDX syntax so the pages compile cleanly.
• scripts/build-portfolio.ts performs a single GitHub API call to assemble src/data/portfolio.generated.json, optionally overriding the GitHub username via the GITHUB_USERNAME environment variable while also probing each repository for preview images.

Custom MDX rendering safeguards

• The MDX component bridge in src/theme/MDXComponents/index.tsx provides fallbacks for unfamiliar React components that may appear in imported remote notes. It introduces universal shims for image components (ImageView, Image) and layout wrappers (RelativeLayout, TextView) so remote content renders gracefully without manual edits.
• The Markdown repair script described above automatically escapes <, >, {, and } outside of code blocks, which prevents runtime crashes when remote documents include raw HTML snippets.

Rich portfolio presentation

• Professional engagements include client names, problem statements, and technology stacks defined in src/data/professionalProjects.json. The page groups them into responsive cards, adds optional imagery, and provides direct links when available.
• Open-source repositories from GitHub surface with star counts, detected topics, language badges, and optional live demo links. Preview thumbnails are fetched automatically when a repository exposes an images/demo.* asset.

Searchable, theme-aware site configuration

• Local full-text search is enabled by @easyops-cn/docusaurus-search-local within docusaurus.config.ts, letting visitors find material across docs, the blog, and custom pages.
• The configuration also toggles dark-mode awareness, wires navbar links to the documentation, portfolio, and blog, and centralizes social links in the footer alongside GitHub and LinkedIn profiles.

Repository Structure

blog/               → Long-form articles and assets
docs/               → Documentation pages, plus imported remote content
scripts/            → Automation utilities for remote docs, images, and portfolio data
src/components/     → Reusable React components for landing content
src/pages/          → Route definitions for the home and portfolio pages
src/theme/          → Theme overrides (MDX shims, social links)
static/             → Static assets served verbatim by Docusaurus

Getting Started

Prerequisites

• Node.js 24.9.0 and npm 11.6.0 (see the engines field in package.json). Consider using a Node version manager to match these versions locally.

Installation

npm install

Refresh remote content (optional but recommended)

The development and build workflows automatically trigger the content pipeline, but you can run the steps manually when iterating on scripts:

npm run fetch:remote-gh-repos       # Builds src/data/portfolio.generated.json
npm run generate:remote-docs        # Detects Markdown files in remote repositories
npm run import:remote-docs          # Downloads the detected Markdown locally
npm run repair:remote-markdown      # Escapes MDX-sensitive characters
npm run fetch:remote-images         # Mirrors relative images referenced by the docs

Adjust the repositories pulled into the docs by editing scripts/remoteSources.ts. To preview a different GitHub profile in the portfolio, set GITHUB_USERNAME=<username> before running npm run fetch:remote-gh-repos.

Local development

npm run start

This spins up the Docusaurus dev server with hot reloading at http://localhost:3000.

Production build

npm run build

Static assets are emitted to the build/ directory. Preview the optimized site locally with:

npm run serve

Deployment

• Publish to GitHub Pages with the built-in command:

  npm run deploy

• If you maintain a separate branch for GitHub Pages, you can push the build/ directory using:

  npm run deploy-gh

Both commands depend on the preconfigured organizationName and projectName fields in docusaurus.config.ts.

Updating content

• Edit docs/intro.mdx for the introductory narrative, tech stack badges, and GitHub stats widgets.
• Add or refine professional project entries in src/data/professionalProjects.json to showcase new work.
• Create blog posts by adding Markdown or MDX files under blog/ and updating blog/authors.yml for author metadata.
• Customize theme visuals and social icons by adjusting files in src/theme/ and the assets inside static/.

Helpful scripts

Command	Purpose
npm run typecheck	Run TypeScript against the site and scripts, ensuring type safety.
npm run clear	Remove cached data generated by Docusaurus between builds.
npm run swizzle	Scaffold theme component overrides.
npm run write-heading-ids	Generate stable heading anchors for Markdown content.
npx docusaurus-mdx-checker	Run this command on your site to obtain a list of files that will fail to compile under MDX v3.

Refer to package.json for the complete list of available commands.