cade.io: Near Computronium

This is the source code for my personal website (cade.io), which is built using Astro and hosted using GitHub Pages. This includes my personal blog posts, prototype projects, and artwork I've made over the years.

It's quite modularized, so feel free to use it as a template or starting point for your own website.

Links

• cade.io - my personal website (live demo)
• GitHub Repository - the source code
• Can I Use? - check browser compatibility for various web features
• Astro Documentation - learn more about the Astro framework

Setup

First, clone this repository from GitHub, and ensure you have installed Node.js/NPM on your machine.

Then, you can install the project's dependencies locally:

npm install

To make sure everything is working, you can start the development server:

npm run dev

Now, you should be able to access it via a web browser at localhost:4321. It will automatically reload and update as you make changes to the source code. Enjoy!

Usage

All commands are run from the root of the project, from a shell:

Command	Action
npm install	Installs dependencies
npm run dev	Starts local dev server at localhost:4321
npm run build	Build your production site to ./dist/
npm run preview	Preview your build locally, before deploying
npm run astro ...	Run CLI commands like astro add, astro check
npm run astro -- --help	Get help using the Astro CLI

Further documentation can be found at the Astro CLI Reference.

Structure

This project mainly follows the official Astro project structure guide, which means many of the paths listed are special:

├── plugins/               # my custom plugins
├── public/                # static assets, copied verbatim
├── src/                   # source code for the site
│   ├── components/        # reusable components
│   ├── layouts/           # reusable layouts
│   ├── content/           # markdown content like blog posts
│   └── pages/             # static pages of content
├── astro.config.ts        # Astro configuration
└── tsconfig.json          # TypeScript configuration

Utilities

Visual Studio Code: Editor and IDE

My personal development setup includes using Visual Studio Code, with the following extensions:

• Astro Language Support Extension astro-build.astro-vscode

You can read more about setting up your own environment in the Astro Editor Setup Guide.

This uses Prettier as the formatting engine. I had to define my configuration options in .prettierrc.json for the Astro extension to format properly. You can customize the syntax choices in the Prettier Configuration Options.

KaTeX: Math Rendering

KaTeX is a way of writing mathematical equations in LaTeX format (as well as other typesetting and diagrams).

I used KaTeX v0.16.21 and stuck it in ./public/ext/katex/, since we still have to ship the CSS and some extension JS files apart from the static renderer.

• KaTeX extension: copy-tex - allows copying the LaTeX source of an equation

npm i katex

And to integrate it in Astro (via astro.config.ts), it needs remark/rehype plugins:

npm install remark-math
npm install rehype-katex

Expressive Code: Syntax Highlighting

Expressive Code is hands-down the best syntax highlighting system I've found. It's easy to drop in, but I've customized it quite a lot.

I use the following plugins (or am experimenting with using them):

• @fujocoded/expressive-code-caption
• @fujocoded/expressive-code-output

npx astro add astro-expressive-code
npm i @expressive-code/plugin-collapsible-sections
npm i @expressive-code/plugin-line-numbers

# community
npm i expressive-code-color-chips

Astro Icon: Icons and SVGs

I use the Astro Icon package to manage SVG icons and components. I override the iconDir as ./public/icons/ in the astro.config.ts file. This way, I will also ship static SVGs for the icons, in case I can't use the component.

npm install astro-icon

As far as finding icons, I use a variety of sources:

• feathericons.com - super high quality, beautiful, but limited selection (preferred)
• remixicon.com

Also, with more customization and sometimes lower quality:

• iconduck.com
• jam-icons.com
• heroicons.dev

Processes

Hosting on GitHub Pages

To deploy to GitHub Pages, we can follow the Official Astro Guide. Specifically, I used cade.io and set up a custom domain for GitHub Pages.

Updating the Favicon

I use Inkscape to maintain my site's favicon in the ./public/favicon.dev.svg file. That includes all the editing layers, text objects, and shapes sources.

After I change it and save the file, the steps to update the site's favicon are:

• Use the RealFaviconGenerator website and upload ./public/favicon.dev.svg to it
• Follow the steps in the workflow configuration
  • I use the same icon for light/dark mode
  • I select 'Use the icon as is` for all inputs
  • I use cade.io as the app name for all boxes
• Download the archive file, and unzip directly into ./public, overwriting the existing files
  • For example: unzip -o ~/Downloads/favicon.zip -d ./public
• Insert the generated HTML code into the ./src/components/BaseHead.astro file

Managing Themes

• Get Rid of Theme Flicker

Converting Fonts

For this website, I have been using the following fonts:

• Ubuntu - for normal prose text, headers, and UI elements
• Ubuntu Mono - for code blocks and monospaced text

You can download these fonts from Google Fonts, but they will be in TTF format. Instead, we'd like to use WOFF2 format which is more optimized for web loading. To do that, we need to install or build Google's implementation.

• MacOS: brew install woff2

Then, after downloading and extracting the font files, you can use the ./scripts/woff2ify script to convert them:

./scripts/woff2ify.sh ./public/fonts ~/Downloads/Ubuntu/*.ttf ~/Downloads/Ubuntu_Mono/*.ttf

Scratch Space

• https://pyodide.org/en/stable/ - for JS embedding of Python code