Quartz Line Age Plugin

A Quartz plugin that displays line authoring age visualization, inspired from the Telomere feature in Cosense(Scrapbox) and Obsidian Git plugin's Line Authoring feature.

Preview

See https://garden.matsuuratomoya.com .

Installation

In your quartz directory,

npm install quartz-line-age

Usage

The plugin is separated into 3 stages

1. LineAgePre - Runs before markdown processing and inserts metadata markers
2. LineAgeMid - Runs after toc is generated, and removed unnecessary html comments from them.
3. LineAgePost - Runs after HTML conversion and transforms markers into styled elements

Usage

You need to add LineAgePre, LineAgeMid and LineAgePost plugins separately.

LineAgePre should be added as a first plugin, LineAgeMid should be placed right after Plugin.Toc(), LineAgePost should be added right after markdown processor.

import { QuartzConfig } from "./quartz/cfg";
import { LineAgePre, LineAgeMid, LineAgePost } from "quartz-line-age";

const config: QuartzConfig = {
  plugins: {
    transformers: [
      LineAgePre(),
      //... ,
      Plugin.TableOfContents(),
      LineAgeMid(),
      Plugin.FrontMatter(),
      Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
      Plugin.GitHubFlavoredMarkdown(),
      //... ,
      LineAgePost({
        maxAgeDays: 365,
        freshColor: { r: 34, g: 197, b: 94 },
        oldColor: { r: 156, g: 163, b: 175 },
        darkModeFreshColor: { r: 34, g: 197, b: 94 },
        darkModeOldColor: { r: 100, g: 116, b: 139 },
      }),
      // ...
    ],
  },
};

export default config;

Options

• enabled (boolean, default: true) - Enable or disable the line age visualization
• maxAgeDays (number, default: 365) - Maximum age in days for the color gradient. Lines older than this will show as completely gray.
• freshColor (RGBColor, default: { r: 34, g: 197, b: 94 }) - RGB color for the newest/freshest lines in light mode (default is green-500)
• oldColor (RGBColor, default: { r: 156, g: 163, b: 175 }) - RGB color for the oldest/stale lines in light mode (default is gray-400)
• darkModeFreshColor (RGBColor, default: { r: 34, g: 197, b: 94 }) - RGB color for the newest/freshest lines in dark mode (default is green-500)
• darkModeOldColor (RGBColor, default: { r: 100, g: 116, b: 139 }) - RGB color for the oldest/stale lines in dark mode (default is slate-500)

Dark Mode Support

The plugin automatically supports dark mode using the prefers-color-scheme CSS media query. You can configure separate colors for light and dark modes:

LineAgePost({
  maxAgeDays: 365,
  // Light mode colors
  freshColor: { r: 34, g: 197, b: 94 },    // green-500
  oldColor: { r: 156, g: 163, b: 175 },    // gray-400
  // Dark mode colors
  darkModeFreshColor: { r: 34, g: 197, b: 94 },   // green-500
  darkModeOldColor: { r: 100, g: 116, b: 139 },   // slate-500 (darker than light mode)
})

The plugin will automatically switch colors based on your system's color scheme preference.

Styling

Include the CSS in your Quartz theme or add it to custom SCSS:

@use "quartz-line-age/src/line-age.css";

Customization

You can customize the appearance by overriding the CSS classes:

.line-age-bar {
  width: 6px; /* Adjust bar width */
  border-radius: 3px; /* Adjust corner radius */
}

.line-age-wrapper:hover .line-age-bar {
  width: 8px; /* Adjust hover width */
}

How It Works

1. The plugin uses git blame to determine when each line was last modified
2. It calculates the age of each line in days
3. Based on the age, it computes a color between green (fresh) and gray (old) for both light and dark modes
4. A small colored bar is added to the left of each line with CSS variables for theme-aware coloring

The color calculation formula:

age_ratio = min(age_in_days / max_age_days, 1.0)
// Uses power function for more pronounced recent changes
adjusted_ratio = age_ratio^(1/2.3)
color = interpolate(fresh_color, old_color, adjusted_ratio)

Colors are calculated separately for light and dark modes and applied using CSS custom properties with prefers-color-scheme media queries.

Examples

Standalone Demo

See example.html for a standalone demonstration of the line age visualization.

You can open it directly in your browser:

# Serve the example locally
python3 -m http.server 8080
# Then open http://localhost:8080/example.html

Command Line Demo

Run the included demo script to see the color calculations:

node demo.js

This will show:

• Color gradient for different ages (0-365+ days)
• Git blame analysis of the demo file itself
• Color values for each line

Integration Test

Test the git blame integration on real files:

node test-integration.js

This demonstrates the actual git integration working on committed files.

Integration Example

See example-usage.js for a complete example of how to integrate this plugin with your Quartz configuration.

Requirements

• Quartz v4.x
• Git repository (for blame information)
• Node.js 16+

Development

# Install dependencies
npm install

# Build the plugin
npm run build

# Run tests
node test-integration.js
node test-path-handling.js
node demo.js