A(valonia)XKCD

XKCD viewer for desktop and browser.

AvaloniaXKCD is an XKCD comic viewer for desktop and browser. It provides a native experience on Windows and Linux, with a browser-based version using WebAssembly.

Features

• Cross-Platform: Native desktop applications for Windows and Linux, plus a browser-based viewer.
• Localization: Supports multiple languages (English and Spanish) with runtime locale detection.
• Modern UI: Responsive interface.
• Developer-Friendly: Structured codebase.

Note

This project is an unofficial XKCD viewer and is not affiliated with XKCD.com.

Getting Started

Prerequisites

• .NET 10 SDK
• Bun (for browser development)
• Docker (optional, for containerized development)

Quick Start

# Clone the repository
git clone https://github.com/dylanlangston/axkcd.git
cd axkcd

# Run the desktop version
make develop-desktop

# Or run the browser version
make develop-browser

Project Structure

The project is organized into several key directories:

axkcd/
├── src/                      # Source code
│   ├── AvaloniaXKCD/         # Core UI and application logic (MVVM)
│   ├── AvaloniaXKCD.Desktop/ # Desktop-specific platform code
│   ├── AvaloniaXKCD.Browser/ # Browser-specific platform code (WASM)
│   ├── XKCDCore/             # Library for interacting with the XKCD API
│   └── ...                   # Supporting projects and tests
├── mirror/                   # Local mirror of XKCD comics
└── makefile                  # Scripts for building, testing, and running

Development

Common Makefile Commands

The makefile automates common development tasks:

Command	Description
setup	Sets up the development environment.
develop-desktop	Runs the desktop application in development mode.
develop-browser	Runs the browser application in development mode.
publish-windows	Builds the application for Windows.
publish-linux	Builds the application for Linux.
publish-browser	Builds the application for the browser.
test	Runs the test suite.
format	Formats the source code.
clean	Cleans the local environment.
help	Displays the help menu with all available commands.

Development Container

For a consistent environment, this project includes a Dev Container. This is the recommended way to work on the project, as it ensures all tools and dependencies are set up correctly.

Technology

Core Stack

• Avalonia UI: A cross-platform UI framework for .NET.
• .NET 10: Platform for building the application.

Tools & Infrastructure

• GitHub Actions: For CI/CD.
• Docker: For a consistent development environment.
• Make: For build and development tasks.
• Bun: For browser development.

Contributing

Contributions welcome. See Contributing Guide.

Resources

• Source Code
• Issue Tracker
• Localization Guide
• XKCD
• Explain XKCD

Acknowledgments

• Randall Munroe for XKCD.
• The Avalonia UI team for the UI framework.

License

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