Oink

Local-First • Hybrid Block-Markdown Knowledge Base • Canvas Graph Visualizer

Key Features • Tech Stack • Getting Started • Architecture • Shortcuts • Contributing

Overview

Oink is a modern, high-performance, local-first markdown workspace and knowledge management platform designed for developers, researchers, and creators.

By combining the block-editing ergonomics of modern canvas tools with the portable, open-standards durability of plain text .md files, Oink offers a powerful editing environment with zero vendor lock-in, zero cloud telemetry, and complete offline privacy.

Key Features

1. Local-First & Zero Lock-In

• Plain Markdown Storage: All documents are stored directly as human-readable .md files on your local file system.
• Git Friendly: Works natively with Git version control, Obsidian vaults, Logseq directories, and any standard text editor.
• Offline Reliability: Instant startup and sub-millisecond file interactions without cloud dependencies.

2. Hybrid Block-Markdown Editing Engine

• Rich Interactive Blocks: Seamlessly convert between raw markdown and structured blocks (Headings, Checklists, Nested Lists, Code Fences, Tables, Blockquotes, Delimiters, and Inline Callouts).
• Media & Embed Support: Drag-and-drop local images, embed web videos (.mp4, YouTube, Vimeo, CodePen), and customize captions directly.
• KaTeX Mathematics: Native inline and block-level LaTeX rendering ($math$ and $$equation$$).

3. Bi-Directional Wikilinks & Canvas Knowledge Graph

• Interlinked Knowledge: Create connections using [[Note Name]] wikilinks with auto-completion and click-to-navigate.
• Interactive Force-Directed Graph: Hardware-accelerated canvas graph that visualizes node relationships, connection density, and orphan documents in real time.

4. Deep Page & Typography Customization

• Per-Page Styling: Configure font family, font size, line height, letter spacing, font weight, and text alignment per document or globally.
• Visual Covers & Icons: Add Unsplash photography or gradient banners, custom emoji icons, and toggleable title headers with YAML frontmatter persistence.
• Distraction-Free Full-Screen Mode: Hide peripheral toolbars and sidebars for an immersive writing session.

5. Floating Multi-Tool Widget Ecosystem

Draggable, resizable, floating desktop tool panels that overlay your workspace:

• Document Outline Widget: Dynamic heading tree with jump-to-section navigation.
• Assistant Panel: Local diagnostic scanner for passive voice, wordiness, grammar suggestions, and AI integrations.
• Quick Terminal: Embedded dev log monitor and shell command runner.
• Extensions & Plugins Widget: Modular extension manager to toggle KaTeX, Daily Journals, Pomodoro timers, and diagrams.
• Document Statistics: Live word count, character count, estimated reading time, and language indicators.
• Code Snippets Library: Instant code templates for Python, TypeScript, SQL, JSON, and Markdown tables.

Technology Stack

Component	Technology	Description
Runtime	Electron 39	Cross-platform desktop runtime with secure IPC architecture
UI Framework	React 19	Modern concurrent UI engine with functional hooks
Language	TypeScript 5.9	Strict type checking across main, preload, and renderer layers
Build Tooling	electron-vite / Vite 7	High-speed HMR bundling and multi-target compilation
Styling	Vanilla CSS + TailwindCSS 4	Custom Brutalist dark theme with responsive glassmorphic overlays
Editor Core	Editor.js	Block-based modular editing framework with custom markdown adapters
Icons	Lucide React	Lightweight, consistent SVG icon system
Background Indexing	Web Workers	Asynchronous tokenization, metadata parsing, and wikilink graph indexing

Getting Started

Prerequisites

Ensure you have the following installed on your machine:

• Node.js >= 20.0.0
• npm, bun, or pnpm

Installation

1. Clone the repository:

   git clone https://github.com/HawkdotDev/oink.git
   cd oink

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

Build & Distribution

To package Oink as a native desktop binary:

# Package for current OS (unpacked directory)
npm run build:unpack

# Build Windows installer (.exe)
npm run build:win

# Build macOS package (.dmg / .zip)
npm run build:mac

# Build Linux package (.AppImage / .deb)
npm run build:linux

Output binaries will be generated in the dist/ directory.

Code Quality & Standards

Oink maintains strict type safety and code quality standards:

# Type check TypeScript across all targets
npm run typecheck

# Run ESLint validation
npm run lint

# Format codebase with Prettier
npm run format

Contributing

Contributions, feature suggestions, and bug reports are welcome!

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please review our Contributing Guidelines and ensure all linting and typecheck passes before submitting PRs.

License

Distributed under the MIT License. See LICENSE for more details.

_{Built with care by the Oink Open Source Community.}