NotepadSharp.PluginSdk 1.0.0-alpha-4

Notepad# Plugin SDK

The official Plugin SDK for Notepad#, enabling developers to extend the cross-platform text editor with custom functionality through a clean, well-documented API.

Overview

The NotepadSharp.PluginSdk provides everything you need to create powerful plugins for Notepad#. Plugins can register commands, manipulate text, interact with the editor, and integrate seamlessly into the application's menu system and keyboard shortcuts.

Key Features

• 🎯 Command Registration - Add menu items and keyboard shortcuts that integrate seamlessly with the application
• 📝 Editor API - Manipulate text, selections, and caret position in the active document
• 🔔 Event System - React to document changes and application events
• 🔌 Isolated Loading - Plugins run in separate AssemblyLoadContext for dependency isolation
• 🛠️ Cross-Platform - Write once, run on Windows, Linux, and macOS
• 📚 Well-Documented - Comprehensive XML documentation and examples

Current Status

This whole project is currently very much in the alpha stages (currently 3rd day of coding as I write this). The API is subject to change, and there are still many features to be implemented.

Installation

Via NuGet (Recommended)

dotnet add package NotepadSharp.PluginSdk

Via Project Reference

dotnet add reference path/to/NotepadSharp.PluginSdk/src/NotepadSharp.PluginSdk.csproj

Quick Start

1. Create a New Plugin Project

dotnet new classlib -n MyAwesomePlugin
cd MyAwesomePlugin
dotnet add package NotepadSharp.PluginSdk
dotnet add package CommunityToolkit.Mvvm

2. Implement IPlugin

using NotepadSharp.PluginSdk;
using CommunityToolkit.Mvvm.Input;
using System.Linq;

namespace MyAwesomePlugin;

public class MyPlugin : IPlugin
{
    public string Id => "Com.Example.MyAwesomePlugin";
    public string Name => "My Awesome Plugin";
    public string Version => "1.0.0";

    private IPluginHost? _host;

    public void Initialize(IPluginHost host)
    {
        _host = host;
        _host.Shell.LogInfo($"Initializing {Name} v{Version}");

        // Register a command
        var definition = new CommandDefinition(
            Id: "Plugin.MyAwesome.DoSomething",
            DisplayName: "Do Something Awesome",
            Description: "Performs an awesome operation on selected text",
            MenuPath: "_Edit/My Plugin",
            SectionId: "PluginCommands",
            SectionWeight: 500,
            MenuWeight: 10,
            ShortcutKey: "Ctrl+Shift+A"
        );

        var command = new RelayCommand(Execute, CanExecute);
        _host.Commands.Register(definition, command);
    }

    private bool CanExecute()
    {
        return _host?.Editor.HasActiveDocument == true &&
               !string.IsNullOrEmpty(_host.Editor.SelectedText);
    }

    private void Execute()
    {
        try
        {
            var text = _host!.Editor.SelectedText;
            var processed = ProcessText(text);
            _host.Editor.ReplaceSelection(processed);
            _host.Shell.LogInfo($"Processed {text.Length} characters");
        }
        catch (Exception ex)
        {
            _host!.Shell.LogError("Failed to process text", ex);
            _host.Shell.ShowError("Error", $"Operation failed: {ex.Message}");
        }
    }

    private string ProcessText(string text)
    {
        // Your awesome text processing logic here
        return text.ToUpper();
    }

    public void Shutdown()
    {
        _host?.Shell.LogInfo($"Shutting down {Name}");
    }
}

3. Build and Deploy

dotnet build -c Release
cp bin/Release/net9.0/MyAwesomePlugin.dll /path/to/notepadsharp/plugins/

Restart Notepad# and your plugin will be loaded automatically!

Documentation

For detailed architecture and design information, see:

• Plugin Architecture - Complete architectural overview
• Plugin System Design - Design decisions and patterns
• Main Notepad# Repository - Host application
• API Reference - Complete API reference

Sample Plugins

Check out these example plugins to learn more:

• ReverseText - Simple text transformation plugin (included in main repository)
• More examples coming soon!

Requirements

• .NET 9.0 SDK or later
• CommunityToolkit.Mvvm (recommended for RelayCommand implementation)
• Notepad# application to run your plugin

Contributing

Contributions to the SDK are welcome! Here's how you can help:

1. Report Issues - Found a bug or limitation? Open an issue
2. Request Features - Suggest new SDK capabilities
3. Submit PRs - Improve documentation or add new features
4. Share Plugins - Create awesome plugins and share them with the community

Roadmap

Planned SDK Enhancements

• Settings API - ISettingsService for plugin configuration persistence
• UI Extensions - Allow plugins to register dockable tool windows
• Enhanced Events - More granular document and application events
• Async Support - Async versions of SDK methods
• Document API - Access to multiple documents, not just active one
• Syntax Highlighting API - Plugin-provided language definitions
• LSP Integration - Language Server Protocol support for plugins

FAQ

Q: Can I use async/await in my plugin?

A: Yes, but remember to marshal back to the UI thread for editor operations. The SDK currently uses synchronous methods, but async support is planned.

Q: How do I debug my plugin?

A: Build your plugin in Debug mode, copy it to the plugins directory, and attach the debugger to the running Notepad# process.

Q: Can plugins depend on other plugins?

A: Not currently, but this is a planned feature. For now, plugins are independent.

Q: What happens if my plugin crashes?

A: Plugin initialization errors are caught and logged. The host application continues running, but your plugin won't be loaded.

Q: Can I access the file system from my plugin?

A: Yes, plugins have full CLR access. Use IPlatformService.GetConfigDirectory() and GetDataDirectory() for platform-appropriate paths.

Q: How do I distribute my plugin?

A: Currently, distribute as a DLL that users copy to the plugins directory. A plugin marketplace is planned for the future.

License

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

Support

• Issues - GitHub Issues
• Discussions - GitHub Discussions
• Main Project - Notepad# Repository

Acknowledgments

• Notepad# - The host application this SDK extends
• CommunityToolkit.Mvvm - Excellent MVVM helpers and command infrastructure
• All plugin developers building amazing extensions!

Build amazing plugins for Notepad# 🚀