stigmergic.dev - Feature Demonstration

stigmergic.dev is a lightweight markdown watcher and renderer built with Go. This document showcases all supported markdown features.

Overview

This project provides real-time markdown rendering with support for:

• Standard markdown formatting
• Legacy features Modern extensions
• Syntax highlighting for code
• Mathematical equations
• Interactive diagrams

Installation

You can install stigmergic using Nix:

1nix profile install github:Buildtall-Systems/stigmergic.dev

Or run directly:

1nix run github:Buildtall-Systems/stigmergic.dev -- /path/to/docs

Architecture

The system follows a simple architecture with three main components:

1. File Watcher - Monitors filesystem changes
2. HTTP Server - Serves rendered content
3. Markdown Parser - Processes markdown with extensions

Core Implementation

Here's the core markdown parser initialization:

 1package markdown
 2
 3import (
 4	"bytes"
 5
 6	"github.com/alecthomas/chroma/v2/formatters/html"
 7	"github.com/yuin/goldmark"
 8	"github.com/yuin/goldmark/extension"
 9	highlighting "github.com/yuin/goldmark-highlighting/v2"
10	"github.com/yuin/goldmark/parser"
11	gmhtml "github.com/yuin/goldmark/renderer/html"
12)
13
14func Parse(source []byte) ([]byte, error) {
15	md := goldmark.New(
16		goldmark.WithExtensions(
17			extension.GFM,
18			highlighting.NewHighlighting(
19				highlighting.WithStyle("monokai"),
20				highlighting.WithFormatOptions(
21					html.WithLineNumbers(true),
22				),
23			),
24			NewMathExtension(),
25			NewMermaidExtension(),
26			NewNostrExtension(),
27		),
28		goldmark.WithParserOptions(
29			parser.WithAutoHeadingID(),
30		),
31		goldmark.WithRendererOptions(
32			gmhtml.WithUnsafe(),
33		),
34	)
35
36	var buf bytes.Buffer
37	if err := md.Convert(source, &buf); err != nil {
38		return nil, err
39	}
40
41	return buf.Bytes(), nil
42}

Feature Matrix

The following table shows browser compatibility:

Project Roadmap

• Basic markdown rendering
• Syntax highlighting
• File watching
• Live reload via SSE
• Theme support
• Full-text search
• Export to PDF
• Plugin system

Mathematical Formulas

The average update latency can be expressed as:

$$\text{latency} = t_{\text{detect}} + t_{\text{process}} + t_{\text{render}}$$

Where performance targets require $t_{\text{total}} < 200\text{ms}$ for optimal user experience.

Inline math works too: $E = mc^2$ demonstrates energy-mass equivalence.

System Architecture Diagram

graph TD
    A[File System] -->|fsnotify| B[Watcher]
    B -->|Events| C[HTTP Server]
    C -->|SSE| D[Browser Client]
    C -->|Render| E[Markdown Parser]
    E -->|HTML| D
    D -->|HTMX| C

    style A fill:#89b8c2
    style B fill:#84a0c6
    style C fill:#a093c7
    style D fill:#b4be82
    style E fill:#e2a478

Data Flow Sequence

sequenceDiagram
    participant FS as File System
    participant W as Watcher
    participant S as Server
    participant B as Browser

    FS->>W: File Modified
    W->>S: Change Event
    S->>B: SSE Message
    B->>S: HTTP GET /file/path
    S->>B: Rendered HTML
    Note over B: HTMX Updates Content

Configuration Options

The server accepts the following configuration via config.toml:

Example configuration snippet: viper.SetDefault("port", 8080)

Community

Join the discussion on Nostr:

• Follow the project:npub1h0706bf312f273ee38df304671b38a94c6ef2313100af8b92898224990f115c
• Latest updates:note11d681c05cb04261a2de191cde2168b867d68aebe086bd11ce5e838b77efe6e20

Performance Benchmarks

Initial testing shows promising results:

• Server startup: < 100ms
• File tree generation: < 500ms (1000 files)
• Markdown rendering: < 50ms per file
• Change detection to update: < 200ms

Conclusion

stigmergic.dev provides a fast, beautiful, and extensible way to read markdown documentation in real-time. Built with modern Go practices and leveraging the power of goldmark, htmx, and templ.

Visit GitHub for source code and contributions.

Generated with stigmergic.dev