glancr

A modern Markdown documentation viewer built with Go and React. glancr provides a clean, fast interface for browsing and viewing Markdown documentation with live reload capabilities during development.

Features

• 🚀 Fast & Lightweight - Single binary deployment with embedded assets
• 📝 Markdown Rendering - Beautiful rendering of Markdown documents
• 🔄 Live Development - Hot reload during development
• 🎨 Modern UI - Clean, responsive React-based interface
• 📱 Mobile Friendly - Responsive design that works on all devices
• 🔧 Easy Setup - Simple development and deployment workflow

Prerequisites

• Go 1.19+
• Node.js 18+ and npm
• Git

Quick Start

Development

1. Clone the repository

   git clone https://github.com/smjklake/glancr.git
   cd glancr
   

2. Install dependencies

   make deps
   

3. Start development servers

   make dev
   

   This will start:

   • Frontend dev server at http://localhost:5173
   • Backend API server at http://localhost:8080

Production Build

1. Build for production

   make build-prod
   

2. Run the binary

   ./dist/glancr
   

   The application will be available at http://localhost:8080

Available Commands

Development

• make dev - Start development environment with live reload
• make build-dev - Build development version (filesystem assets)
• make test - Run Go tests

Production

• make build-prod - Build production version (embedded assets)
• make release - Clean build for production release
• make build-cross-prod - Build for multiple platforms

Utilities

• make clean - Clean build artifacts
• make clean-all - Deep clean including node_modules
• make deps - Install all dependencies
• make help - Show all available commands

Project Structure

glancr/
├── cmd/
│   └── server/          # Application entry point
│       └── main.go
├── internal/            # Private application code
│   ├── auth/           # Authentication logic
│   └── fs/             # Asset handling (dev/prod)
├── ui/                 # React frontend
│   ├── src/
│   ├── public/
│   └── package.json
├── dist/               # Build output
├── Makefile           # Build automation
├── dev.sh             # Development script
└── go.mod             # Go module definition

Architecture

glancr uses a clean architecture with clear separation between frontend and backend:

• Backend (Go): Serves the React SPA and provides API endpoints
• Frontend (React): Modern TypeScript-based UI with Vite tooling
• Asset Handling: Development mode serves from filesystem, production embeds assets in binary
• Build System: Makefile orchestrates both Go and Node.js build processes

Development Workflow

Adding Features

1. Backend changes: Add logic in internal/ packages
2. Frontend changes: Modify React components in ui/src/
3. API endpoints: Update server routes in cmd/server/main.go

Testing

# Run Go tests
make test

# Run with production build tags
make test-prod

# Run all tests
make test-all

Code Quality

The frontend includes:

• ESLint for code linting
• Prettier for code formatting
• TypeScript for type safety

cd ui
npm run lint          # Check for linting issues
npm run lint:fix      # Fix auto-fixable issues
npm run format        # Format code with Prettier

Deployment

Single Binary Deployment

Build and deploy the production binary:

make release
scp dist/glancr user@server:/path/to/deployment/

Cross-Platform Builds

Generate binaries for multiple platforms:

make build-cross-prod

Produces:

• glancr-linux-amd64
• glancr-darwin-amd64
• glancr-darwin-arm64
• glancr-windows-amd64.exe

Configuration

Currently glancr runs with minimal configuration. The server starts on port 8080 by default.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (make test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow Go conventions and use gofmt
• Write tests for new functionality
• Use TypeScript for frontend development
• Run make lint before committing
• Keep commits atomic and well-described

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Go and React
• Bundled with Vite
• Styled with modern CSS practices

---

glancr - Making documentation beautiful, one markdown file at a time. ✨