Ryze Blog

Aureus - A CLI for Repository Automation

Subhashis Hansda — Sat, 30 May 2026 00:00:00 GMT

What Is Aureus?

Repository compliance is often an afterthought - bolted on with brittle shell scripts that work on one machine and fail silently on another. Manual setup of Git hooks, Commitlint, and semantic release tooling is error-prone: team members diverge in local configurations, and a single malformed commit breaks the changelog pipeline.

Aureus is a CLI tool that wraps all of this into a single, idempotent command. It scaffolds project conventions, enforces commit standards, and automates versioning and changelog generation - across npm, pnpm, yarn, and bun.

Get Started

Aureus is open source under the MIT license:

GitHub: github.com/A58361/aureus
npm: npmjs.com/package/aureus

npx aureus init my-project

Installation

npm install -g aureus

Or run it without installing:

npx aureus init my-project

Requirements: Node.js 18 or newer, Git, and optionally the GitHub CLI for repository creation features.

Core Commands

`aureus init [folder]`

Scaffolds a complete repository setup in the specified folder (defaults to the current directory). This is the main entry point - it walks you through a few prompts and generates everything you need.

`aureus create <component>`

Add individual components to an existing project on demand:

Component	What it does
`license`	Generates a license file (MIT, GPL-3.0, Apache-2.0, etc.)
`gitignore`	Adds a `.gitignore` for your project type
`pull-request`	Creates a PR template in `.github/`
`issue`	Creates bug report and feature request templates
`code-of-conduct`	Generates a Contributor Covenant v2.0
`husky-hooks`	Wires up `commit-msg` and `pre-push` hooks
`github-actions`	Adds a release workflow
`github-repo`	Creates a GitHub repository via `gh` CLI

`aureus view <component>`

Preview templates and configuration before creating them. Useful for seeing what will be generated without writing any files.

`aureus commit`

An interactive TUI for writing conventional commits. It guides you through selecting a commit type, adding an optional scope, writing the message, and flagging breaking changes - no need to remember conventional commit syntax.

Supported types:

Type	Purpose
`feat`	A new feature
`fix`	A bug fix
`refactor`	Code rewrites or restructuring
`build`	Changes affecting build components
`chore`	Changes that don't modify app logic
`test`	Adding or correcting tests
`ops`	Changes to operational components
`revert`	Reverts a previous commit

Automatic Versioning

`aureus bump [--dry-run]`

This is where Aureus shines. It analyses all commits since the last git tag, determines the correct semantic version bump (major / minor / patch), updates package.json, generates a changelog entry, and creates a git tag - all in one step.

# Preview what would change
aureus bump --dry-run

# Apply the bump
aureus bump

The commit analysis follows the conventional commits spec:

Commits with breaking changes or feat: that include BREAKING CHANGE trigger a major bump
feat: commits trigger a minor bump
fix: and other commits trigger a patch bump

This is typically wired into a pre-push Husky hook so that versioning and changelog stay in sync automatically - every push bumps the version and updates the changelog before the code leaves your machine.

Git Hooks Workflow

When you run aureus create husky-hooks (or select Husky support during aureus init), two hooks are configured:

commit-msg - runs aureus verify on the commit message to enforce conventional commit format. Non-compliant messages are rejected before the commit completes.
pre-push - runs aureus bump to bump the version, update CHANGELOG.md, and create a git tag before pushing.

Existing hook files are preserved and extended when possible - Aureus won't overwrite custom hooks you already have.

Configuration

Aureus stores user preferences in ~/.aureus/config.json and reuses them across runs:

Key	Description	Default
`author_name`	Default author name	-
`package_manager`	Preferred package manager	`pnpm`
`license`	Default license	`mit`
`gitignore`	Default .gitignore template	`node`
`github_repo_visibility`	GitHub repo visibility	`public`
`github_remote_protocol`	Git remote protocol	`ssh`
`github_username`	Your GitHub username	-
`contact`	Contact email for code of conduct	-

Configuration is read from ~/.aureus/config.json and can be overridden per-project via a .aureusrc file or package.json extensions key.

Architecture

Aureus is built with a modular orchestration engine at its core:

Async child-process pooling with configurable concurrency limits and per-step timeout guards ensures scaffold operations run in parallel where possible and fail gracefully.
Config-driven scaffolding layers read from a declarative spec - either a .aureusrc file or package.json extensions - to determine which modules to activate. The resolution algorithm prioritises explicit config over convention, with sensible defaults for each detected project type.
Each pipeline step (hook init, commitlint config, semantic release setup) is an isolated module that emits structured events, making it easy to add new components without touching existing code.

The CLI itself is written in TypeScript, built with tsup, and uses Commander.js for argument parsing and Enquirer for the interactive TUI prompts.

Real Usage: Ryze

This very site uses Aureus. The .husky/ directory in the Ryze repository was scaffolded with Aureus and the hooks are managed by it:

.husky/commit-msg runs aureus verify to ensure every commit follows conventional commits
.husky/pre-push runs aureus bump to auto-version before pushing

Every release you see in the Ryze changelog was generated by Aureus. The tool eats its own dogfood.

Ryze - A Blog & Portfolio Starter Built with Astro 6

Subhashis Hansda — Sun, 24 May 2026 00:00:00 GMT

This post talks about everything Ryze ships out of the box, how to customize it and my thoughts on using Astro for something like this.

Get Started

Ryze is a modern blog + portfolio starter built on Astro 6, React 19, Tailwind CSS 4, and shadcn/ui. It is the foundation this very site runs on - what you are reading right now was authored in Markdown and rendered by Ryze.

Ryze is open source under the GPL-3.0 license. You can find the repository, read the full documentation, and submit issues or feature requests on GitHub.

Why Astro?

Ryze is built on Astro because Astro is uniquely suited for content-driven sites. Every page is static by default - zero JavaScript until an interactive island needs it. View transitions between pages are built-in. Content collections provide type-safe frontmatter validation. The build output is pure HTML and CSS with minimal JS.

For a blog and portfolio, this means:

Fast load times - most pages have zero JS
Great SEO - everything is server-rendered HTML
Low hosting cost - static files can be served from any CDN
Future-proof - your content is markdown, not locked in a CMS

What Ryze Ships With

Content & Pages Out of the Box

Ryze comes with five page types pre-built:

Page	Route	Description
Home	`/`	Configurable hero introduction, featured blog posts, featured portfolio projects (order configurable)
Blog	`/blog`	Filterable listing of all posts
Blog Post	`/blog/:id`	Full markdown-rendered article with KaTeX math, Shiki code highlighting, auto-generated figure captions, and Mermaid diagrams
Portfolio	`/portfolio`	Filterable project gallery
Portfolio Project	`/portfolio/:id`	Full project detail with image carousel, links, and tabbed sections
Resume	`/resume`	Full resume page driven by JSON config

There is also a custom 404 page, a dynamic robots.txt, and an RSS feed at /rss.xml.

Markdown Features

Every blog post gets these features for free:

Syntax highlighting via Shiki with github-light / github-dark themes - just write fenced code blocks
LaTeX math via KaTeX - inline with $...$ , display with $$...$$
Auto-wrapped <figure> elements for images - the alt text becomes the <figcaption>
External links open in a new tab with rel="nofollow noopener noreferrer" automatically
GFM support - tables, task lists, strikethrough, autolinks
Heading anchor links - hover any heading to get a permalink
Mermaid diagrams - write ```mermaid fenced code blocks and they render as flowcharts, sequence diagrams, and more, with automatic light/dark theme switching

All of this is configured declaratively in astro.config.mjs via remark and rehype plugins. No per-post configuration needed.

Interactive Components

Ryze ships a set of React island components:

Theme toggle with localStorage persistence and system preference detection
3D perspective tilt on hover
Image gallery carousel with keyboard and mouse wheel navigation
Category/tag filtering with sort controls for both blog and portfolio

All of these are built as Astro islands (client-side React components), so they only load JavaScript when they become interactive - the rest of the page is pure static HTML.

UI Component Library

Ryze includes curated shadcn/ui components in the base-vega style - buttons, breadcrumbs, checkboxes, popovers, and more. All are tree-shakeable TypeScript components with Tailwind-based theming.

Styling

The design system is built entirely with Tailwind CSS 4:

A zinc-based neutral palette that works in both light and dark mode
Motion reduction support via prefers-reduced-motion

Typography for blog content is separately styled in typography.css - headings, blockquotes, code blocks, tables, details/summary, and task lists all get intentional styling.

Search

Full-text search is powered by Pagefind, indexed at build time. Press mod+k or click the search button to search all blog posts. The search UI is styled to match the rest of the design.

SEO & Open Graph

Ryze handles search engine optimization across every page:

Open Graph tags - locale, title, description, URL, type, site name, and image for rich social previews
Twitter Cards - summary_large_image card for Twitter/X embeds
Canonical URLs - prevents duplicate content issues by pointing search engines to the authoritative URL
Article metadata - article:published_time and article:tag for each tag on blog posts
Sitemap - auto-generated by @astrojs/sitemap at /sitemap-index.xml
Dynamic robots.txt - allows all crawlers and references the sitemap
RSS feed - full-content feed at /rss.xml with all non-draft posts
Google site verification - via PUBLIC_GOOGLE_SITE_VERIFICATION environment variable

Dynamic OG Images

Every page gets a unique Open Graph image generated at build time using Satori (JSX → SVG) and Sharp (SVG → PNG):

/og/default.png - site-wide fallback OG image
/og/blog/[id].png - per-post OG image showing title, description, category badge, and formatted date
/og/portfolio/[id].png - per-project OG image with the same design

All OG images use Geist fonts loaded from local assets, a dark background (#18181b), and an orange accent dot. The shared generation logic lives in src/lib/og.ts.

Site Configuration

Everything is driven by config files - no editing of components needed:

src/site-config.json - site-wide settings: domain, navigation, feature toggles, hero introduction, social links, CTA buttons, and featured section ordering.

{
  "domain": "https://your-site.com",
  "navigationItems": ["portfolio", "blog"],
  "bPageFind": true,
  "bThemeToggle": true,
  "bRssFeed": true,
  "introduction": {
    "badges": ["Your Title"],
    "heading": "Your Name",
    "description": "Your bio..."
  },
  "featured": {
    "portfolio": { "visible": true },
    "blog": { "visible": true }
  }
}

src/portfolio-config.json - array of project objects with id, date, category, title, description, tags, introduction, links, video URL, and architecture brief.

src/resume-config.json - complete resume data: personal info, social links, work experience, education, skills, projects, certifications, courses, languages, volunteering, publications.

How to Customize Ryze

Ryze is designed to be forked and made your own with minimal friction.

1. Site Identity

Edit src/site-config.json to set your name, bio, social links, navigation, and featured sections. The homepage hero, header navigation, and footer all pull from this file.

2. Blog Posts

Add .md or .mdx files to src/content/blog/. Each post needs frontmatter following this schema:

---
draft: false
date: "24-05-2026"
title: "Your Post Title"
description: "A short summary"
category: "engineering" # "engineering" | "workflow" | "strategy" | "devlog"
tags: ["tag1", "tag2"]
author: "Your Name"
---

Posts are automatically picked up by Astro's content collections - no registration needed.

3. Portfolio Projects

Edit src/portfolio-config.json. Each project needs an id, title, description, category, links, and optional image paths. Add project images to src/assets/portfolio/<id>/.

4. Resume

Edit src/resume-config.json - work experience, education, skills, certifications, projects, publications, everything is there as mock data you can replace.

5. Theme Colors

The color palette is defined as CSS custom properties in src/styles/global.css. Change the values in :root (light) and .dark (dark) to rebrand the entire site. All shadcn components respect these variables.

6. Remove Features

Don't need a portfolio? Set "visible": false in site-config and remove the navigation item. Don't want search? Set "bPageFind": false. Each feature is independently removable.

How I Built This Site with Ryze

This very site - the one you are reading this post on - was built using Ryze as the starter.

Here is exactly what I did:

Forked the repository and ran pnpm install
Updated site-config.json with my name, bio, social links, and contact info
Wrote blog posts as .md files in src/content/blog/
Replaced portfolio images in src/assets/portfolio/ with actual project screenshots
Customized the resume by editing resume-config.json
Changed the domain in astro.config.mjs and site-config.json
Ran pnpm build and deployed to Cloudflare Pages

That is it. No boilerplate to write, no components to wire up, no CSS to start from scratch. The entire site - homepage hero, filterable blog, portfolio gallery, resume, RSS feed, search, dark mode - was functional after just editing JSON and writing markdown.

What I Changed Beyond the Config

I did end up tweaking a few things to make the site feel like my own:

Changed the favicon.svg in public/
Updated the background.svg used in the tilt card
Removed portfolio projects I did not need and replaced the mock data with real ones
Wrote custom copy for the introduction, CTA sections, and about content

Not a single component needed modification. That is the point of Ryze - it handles the entire UI layer so you can focus on content.

Closing Thoughts

Ryze is my take on what a modern personal site starter should be - fast by default, extensible by design, and focused entirely on your content. Star it on Github if you find it useful. Contributions and issues are always welcome.

Markdown Showcase - Every Feature on Ryze

Subhashis Hansda — Tue, 19 May 2026 00:00:00 GMT

This page demonstrates every markdown feature rendered on Ryze. Use it as a reference when writing your own posts. All code blocks are highlighted with Shiki, math renders via KaTeX, external links open in new tabs, and images get automatic captions from alt text.

Headings

Heading 2 - `h2`

Heading 3 - `h3`

Heading 4 - `h4`

Each heading has an auto-generated anchor link (the # symbol that appears on hover). Click it to copy a direct URL to that section.

Text Formatting

Bold text using **double asterisks**.

Italic text using *single asterisks*.

Bold and italic using ***triple asterisks***.

~~Strikethrough~~ using ~~double tildes~~.

<mark>Highlighted text</mark> using <mark> HTML tags.

<abbr title="Cascading Style Sheets">CSS</abbr> - hover over abbreviations to see the full title.

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy, or <kbd>Cmd</kbd> + <kbd>K</kbd> to open the command palette.

Links

Internal link to the home page

External link to Astro's docs - opens in a new tab with rel="nofollow noopener noreferrer".

Lists

Unordered

Item one
Item two
- Nested item A
- Nested item B
Item three

Ordered

First step
Second step
1. Sub-step A
2. Sub-step B
Third step

Task Lists

[x] Write the markdown showcase
[x] Install remark and rehype plugins
[ ] Add a dark mode toggle
[ ] Publish the blog post

Blockquotes

This is a standard blockquote. It uses a left border and muted text colour to distinguish it from body content.

A longer blockquote that spans multiple lines to show how line wrapping behaves within the blockquote component. The styling includes consistent padding, a left border, and appropriate spacing from surrounding elements.

Inline Code

Use the Array.prototype.map() method to transform arrays. Variable names like config, theme, and backgroundColor are rendered with the Shiki inline code style - dark background in light mode, light background in dark mode.

Code Blocks

Python

from datetime import datetime, timedelta

def generate_date_range(start: str, days: int) -> list[str]:
    start_date = datetime.strptime(start, "%Y-%m-%d")
    return [
        (start_date + timedelta(days=i)).strftime("%Y-%m-%d")
        for i in range(days)
    ]

print(generate_date_range("2026-05-01", 7))
# Output: ['2026-05-01', '2026-05-02', ..., '2026-05-07']

JSX / TSX

import { useState } from "react";

interface CounterProps {
  initial?: number;
}

export default function Counter({ initial = 0 }: CounterProps) {
  const [count, setCount] = useState(initial);

  return (
    <div className="counter">
      <p>Count: {count}</p>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
    </div>
  );
}

CSS

.container {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 1.5rem;
  padding: 2rem;
}

.card {
  border: 1px solid var(--border);
  border-radius: var(--radius);
  padding: 1.5rem;
  transition: box-shadow 0.2s ease;
}

.card:hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

Go

package main

import (
	"fmt"
	"time"
)

func main() {
	now := time.Now()
	fmt.Printf("Current time: %s\n", now.Format(time.RFC1123))
}

Diagrams

Fenced code blocks tagged with mermaid are rendered as interactive SVG diagrams by Mermaid.js. The theme automatically switches between light and dark to match your site's appearance.

Flowchart

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Fix it]
    D --> B

Sequence Diagram

sequenceDiagram
    participant U as User
    participant B as Browser
    participant S as Server
    U->>B: Clicks link
    B->>S: GET /page
    S-->>B: HTML response
    B-->>U: Renders page

Tables

Feature	Plugin	Status
Heading anchors	`rehype-slug` + `rehype-autolink-headings`	Active
External link handling	`rehype-external-links`	Active
Math rendering	`remark-math` + `rehype-katex`	Active
Automatic figure captions	`rehype-figure`	Active
Syntax highlighting	Shiki (built-in)	Active
Mermaid diagrams	`astro-mermaid`	Active

Images

The image above is wrapped in a <figure> element by rehype-figure, with the alt text rendered as a <figcaption> below the image.

Mathematics

Inline Math

The quadratic formula $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ solves $ax^2 + bx + c = 0$.

Euler's identity: $e^{i\pi} + 1 = 0$.

Display Math

$$ \int_{-\infty}^{\infty} e^{-x^2} , dx = \sqrt{\pi} $$

$$ \sum_{k=1}^{n} k = \frac{n(n+1)}{2} $$

$$ \begin{pmatrix} a & b \ c & d \end{pmatrix}^{-1} = \frac{1}{ad - bc} \begin{pmatrix} d & -b \ -c & a \end{pmatrix} $$

Details and Summary

<details> <summary>Click to reveal implementation notes</summary>

This is hidden content inside a <details> element. You can use these for spoilers, collapsible code explanations, or supplementary information that doesn't need to be visible upfront.

The <details> element is native HTML
No JavaScript required
Styled to match the blog's border and spacing tokens

</details>

Mixed Content Example

A Tip for Writers

Good documentation is not written in hindsight - it's written alongside the code.

When documenting APIs, include concrete examples in every section. Users rarely read prose top-to-bottom; they scroll to the code block first, then scan the surrounding explanation.

// Bad: no example
// The authenticate function validates credentials.

// Good: example included
// The authenticate function validates credentials.
const user = await authenticate("admin@example.com", "s3cret");
console.log(user.role); // "admin"

This approach - a short blockquote for emphasis, bold for key terms, and a side-by-side code comparison - keeps readers engaged and learning faster.

What You Can Do With Plugins

All the features on this page are powered by a small set of remark/rehype plugins configured in astro.config.mjs:

rehype-external-links - opens external links in a new tab with security attributes
remark-math + rehype-katex - renders $LaTeX$ math expressions
rehype-figure - wraps images in semantic <figure> elements with captions
astro-mermaid - renders ```mermaid code blocks as SVG diagrams via Mermaid.js
Shiki - syntax highlights every fenced code block with the github-dark theme
GFM (built-in) - tables, task lists, strikethrough, and autolinks

To add any of these to your own posts, just write standard markdown - the plugins handle the rest at build time.

Ryze Blog

Aureus - A CLI for Repository Automation

What Is Aureus?

Get Started

Installation

Core Commands

aureus init [folder]

aureus create <component>

aureus view <component>

aureus commit

Automatic Versioning

aureus bump [--dry-run]

Git Hooks Workflow

Configuration

Architecture

Real Usage: Ryze

Ryze - A Blog & Portfolio Starter Built with Astro 6

Get Started

Why Astro?

What Ryze Ships With

Content & Pages Out of the Box

Markdown Features

Interactive Components

UI Component Library

Styling

Search

SEO & Open Graph

Dynamic OG Images

Site Configuration

How to Customize Ryze

1. Site Identity

2. Blog Posts

3. Portfolio Projects

4. Resume

5. Theme Colors

6. Remove Features

How I Built This Site with Ryze

What I Changed Beyond the Config

Closing Thoughts

Markdown Showcase - Every Feature on Ryze

Headings

Heading 2 - h2

Heading 3 - h3

Heading 4 - h4

Text Formatting

Links

Lists

Unordered

Ordered

Task Lists

Blockquotes

Inline Code

Code Blocks

Python

JSX / TSX

CSS

Go

Diagrams

Flowchart

Sequence Diagram

Tables

Images

Mathematics

Inline Math

Display Math

Details and Summary

Mixed Content Example

A Tip for Writers

What You Can Do With Plugins

`aureus init [folder]`

`aureus create <component>`

`aureus view <component>`

`aureus commit`

`aureus bump [--dry-run]`

Heading 2 - `h2`

Heading 3 - `h3`

Heading 4 - `h4`