at-ref

Overview

at-ref is a developer tool that enhances atomic documentation workflows by providing visual cues and interactive features for @/path references in markdown files. It is available both as a VS Code extension and as an npm package.

The Problem

When working with atomic documentation - small, focused, interconnected documents - managing references between files becomes critical. Traditional markdown links work, but they lack:

• Visual distinction from regular text
• Quick validation of reference targets
• Easy navigation without leaving context

Features

Visual Cues for @References

The extension highlights @/path style references in your markdown files, making them instantly recognizable. This visual distinction helps you quickly scan documents and identify all cross-references.

Clickable Links

References become interactive - click on any @/path reference to navigate directly to the target file. This transforms your documentation into a connected knowledge graph you can traverse effortlessly.

Broken Reference Detection

One of the most valuable features is automatic detection of broken references. When a referenced file doesn’t exist or has been moved, the extension alerts you immediately, helping maintain documentation integrity.

Installation

VS Code Extension

Install directly from the VS Code marketplace or via the Extensions panel.

npm Package

npm install @u-b/at-ref

The npm package (@u-b/at-ref) allows you to integrate at-ref functionality into your own tools and build systems.

Use Cases

• AI Development Workflows - Pair with frameworks like all-agents for atomic documentation that AI can reliably navigate
• Knowledge Management - Build interconnected documentation with confidence that links stay valid
• Monorepo Documentation - Reference docs across packages with visual clarity

Documentation

Full documentation and usage examples are available at the project homepage.