blog/README.md

🍭 My blog built with Astro + TypeScript. Neat.

kremalicious.com

---

• 🎉 Features
  • 🌅 Image handling
  • 🎆 EXIF extraction
  • 💰 Cryptocurrency donation via Web3/MetaMask
  • 🔍 Search
  • 🕸 Related Posts
  • 📝 GitHub changelog rendering
  • 🌗 Theme Switcher
  • 💎 SVG assets as components
  • redirect_from
  • RSS & JSON feeds
• ✨ Development
  • 🔮 Linting
  • 🔮 Type Checking
  • 👩‍🔬 Testing
• 🎈 Content creation helpers
  • Add a new post
• 🚚 Deployment
  • S3 Deployment
• 🏛 Licenses
  • Posts
  • Photos & images

---

🎉 Features

The whole blog is a statically exported site built with Astro and TypeScript. Almost all components are Astro or native Web Components, with some React components loaded client-side.

Styling happens through a combination of basic global styles and on components level either through CSS modules or CSS in <style> tags within Astro components.

Content lives under content/ and Astro creates a content collection for each subfolder, which are then queried in components. Every post is a folder with a markdown file and all respective post assets colocated inside.

Retrieving content collections will enrich every post's frontmatter metadata, like extracting date and slug from the post folder name, or exif extraction for photos.

🌅 Image handling

Uses Astro's native astro:assets feature, all required image sizes are automatically generated from source images, working in combination with my own custom <picture> component. Making heavy use of Astro's getImage() and custom markup results in full image sizing control and properly object-fit images with varying aspect ratios.

Teaser images are all defined in a post's frontmatter image key, which is then passed to the <Picture /> component for display.

If you want to know how this works, have a look at the respective files:

• src/components/Picture/index.astro
• src/components/Picture/index.module.css

🎆 EXIF extraction

Automatically extracts EXIF & IPTC metadata from my photos and adds it to markdown frontmatter of respective photo posts. For minimal overhead, fast-exif & node-iptc is used to parse every JPG file whenever a content collection is accessed.

In the end looks like this, including location display with pigeon-maps:

If you want to know how this works, have a look at the respective files:

• EXIF extraction with readOutExif() helper in src/lib/exif/index.ts
• the loadAndFormatCollection() helper in src/lib/astro.ts
• output through src/components/Exif/

💰 Cryptocurrency donation via Web3/MetaMask

Lets visitors say thanks with Bitcoin or Ether. Uses RainbowKit for wallet connection & wagmi for sending transactions via browser wallets.

If you want to know how this works, have a look at the respective components under

• src/components/Donation/

🔍 Search

A global search is provided with fuse.js. Whenever search is opened, all posts metadata is fetched, which is then queried against when the search field is used. This prevents a huge search index from being bundled in the site build.

If you want to know how this works, have a look at the respective components under

• src/components/Search/

🕸 Related Posts

Under each post a list of related posts is displayed which are based on the tags and other metadata of the currently viewed post, also done with fuse.js.

If you want to know how this works, have a look at the respective component under

• src/components/RelatedPosts/

📝 GitHub changelog rendering

Adds ability to show contents of a changelog, rendered from a CHANGELOG.md on GitHub from the given repository. The use case is to enhance release posts about projects hosted on GitHub. Makes use of the GitHub GraphQL API.

Adding this to a post's YAML frontmatter:

changelog: kremalicious/gatsby-plugin-matomo

will render this at the end of the post:

See it live e.g. on Matomo plugin for Gatsby.

If you want to know how this works, have a look at the respective component under

• src/components/Changelog/
• the getRepo() helper in src/lib/github.ts

🌗 Theme Switcher

Includes a theme switcher which allows user to toggle between a light and a dark theme. Switching between them also happens automatically based on user's system preferences. Uses nanostores to share its state between components/frameworks.

If you want to know how, have a look at the respective components:

• src/components/ThemeSwitch/
• src/stores/theme.ts

💎 SVG assets as components

All SVG assets under src/images/ and from select iconset dependencies are converted to Astro components before building the site. Compiled components are placed under src/images/components/ and all include the cleaned SVGs as inline HTML.

All SVGs can then be imported from @images/components in all Astro components.

If you want to know how this works, have a look at the respective files:

• scripts/create-icons/

redirect_from

Still a remnant of the old Jekyll days, which survived in gatsby-redirect-from and now works in Astro. For all post slugs defined in a redirect_from frontmatter key, redirects will be put in place by Astro.

Before building the site, a script scans all markdown files and creates a json file under .config/redirects.json. This file is then imported into astro.config.ts under its redirects option.

If you want to know how, have a look at the respective files:

• scripts/redirect-from.ts

RSS & JSON feeds

✨ Development

git clone git@github.com:kremalicious/blog.git
cd blog/

# required env vars
cp .env.sample .env
vi .env

npm i
npm start

🔮 Linting

ESlint, Prettier, and Stylelint are setup for all linting purposes:

npm run lint

To automatically format all code files:

npm run format

🔮 Type Checking

Type checking can be invoked to check all TypeScript code, including within .astro files:

npm run typecheck

👩‍🔬 Testing

Test suite is setup with Vitest, react-testing-library, and Playwright.

All unit test files live beside the respective component with naming pattern *.test.ts(x). Integration test files live under ./test/e2e/ exclusively, with naming pattern *.spec.ts.

Testing setup, fixtures, and mocks shared between unit & integration tests can be found in ./test folder.

To run all unit tests:

npm run test:unit

For End-to-End integration testing, ideally run against the production build:

npm run build && npm run preview

# mapping `playwright` command
npm run test:e2e
npm run test:e2e -- --ui
npm run test:e2e -- path/to/file.spec.ts.
npm run test:e2e -- --update-snapshots

🎈 Content creation helpers

Add a new post

npm run new "Hello World"
npm run new "Hello World" 2017-12-27

Create a new photo post with date, title & description pre-filled from EXIF/IPTC data of a given image file:

npm run new photo /path/to/photo.jpg
npm run new photo /path/to/photo.jpg "Hello Photo Post"

• scripts/new/

🚚 Deployment

Every branch or Pull Request is automatically deployed by Vercel with their GitHub integration. A link to a preview deployment will appear under each Pull Request. Vercel is not used for the production deployment.

S3 Deployment

The latest deployment of the main branch is automatically deployed to S3 from the GitHub Action as the production deployment, aliased to kremalicious.com. The deploy command simply calls the scripts/deploy-s3.sh script, syncing the contents of the dist/ folder to S3:

npm run deploy:s3

🏛 Licenses

The MIT License (MIT)

EXCEPT FOR:

Posts

All post content under ./content/articles & ./content/links is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Photos & images

All photos & image assets are plain ol' copyright.

Copyright (c) 2008–2023 Matthias Kretschmann

Don't care if you fork & play with it, but you're not allowed to publish anything from it as a whole without my written permission. Also please be aware, the combination of typography, colors & layout makes up my brand identity. So please don't just clone everything, but rather do a remix!