GuideNH-IDEA

Kotlin IntelliJ IDEA support for GuideNH Markdown authoring. The plugin keeps the Markdown editor intact while adding GuideNH-aware parsing and workspace semantics.

Implemented editor features include schema diagnostics and quick fixes, project-local Kotlin schema extraction, page/resource/item/ore references, definitions, Find Usages, hover documentation, GuideNH-aware completion and indentation, workspace symbols, locale-aware indexing, IntelliJ Live Template snippets, runtime bridge actions/status, runtime semantic/preview adapters, viewport-bounded item PNG inlays, and native item picker/drop handling. The picker previews and writes ItemStack ids with meta/NBT/count controls when the target schema supports them.

The plugin also bundles the offline Ponder JSON schema at src/main/resources/guidenh/schema/ponder_schema.json. Add guidenh://schema/ponder.json to a Ponder document's $schema field and associate that URI with the bundled file in IntelliJ's JSON Schema Mappings when editing standalone Ponder JSON files.

The bundled Markdown preview supports GuideNH table extensions for column spans (||), row spans (^^), multiline rows (a trailing backslash), headerless tables, cell Markdown, grouped HTML rows, and cell inline attributes.

The runtime bridge uses GuideNH protocol version 1 (hello, capabilities, semantic.query, document.validate, preview.search, and preview.resolve) with local-host validation, token configuration, reconnect, bounded envelopes, capability negotiation, and guarded semantic/diagnostic payloads by default.

Build locally with:

.\gradlew.bat compileKotlin
.\gradlew.bat buildPlugin

The generated plugin ZIP is written to build/distributions/. The plugin has no GUI Designer forms, so IntelliJ bytecode instrumentation is disabled and no Java compiler Ant dependency is required. CI builds the plugin, runs verification, and uploads plugin-distribution on pull requests and pushes to main.

Connect repository to GitHub

1. Create a new repository on GitHub.
2. Run the following commands to initialize and push this project to the repository created in step 1:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/<username>/<repository>.git
git push -u origin main

3. Configure publishing secrets in the GitHub repository settings:

Secret	Description
PUBLISH_TOKEN	JetBrains Marketplace token — generate here
CERTIFICATE_CHAIN	Plugin signing certificate chain (docs)
PRIVATE_KEY	Plugin signing private key
PRIVATE_KEY_PASSWORD	Password for the private key

Overview

This repository implements an IntelliJ Platform plugin.

Current Functionality

The plugin adds a GuideNH tool window with runtime status/actions and integrates GuideNH diagnostics, completion, navigation, references, hover documentation, and structure symbols into Markdown editing.

Plugin structure

A generated project contains the following content structure:

.
├── .github/                GitHub Workflows, issue templates, and Dependabot configuration
├── .run/                   Predefined Run/Debug Configurations
├── gradle
│   ├── wrapper/            Gradle Wrapper
│   ├── libs.versions.toml  Version catalog
├── src                     Plugin sources
│   └── main
│       ├── kotlin/         Kotlin production sources
│       └── resources/      Plugin resources
│           ├── META-INF/   Plugin configuration file and logo
│           └── messages/   Message bundles
├── .gitignore              Git ignoring rules
├── build.gradle.kts        Gradle build configuration
├── gradle.properties       Gradle configuration properties
├── gradlew                 *nix Gradle Wrapper script
├── gradlew.bat             Windows Gradle Wrapper script
├── README.md               This file
└── settings.gradle.kts     Gradle project settings

In addition to the configuration files, the most crucial part is the src directory, which contains our implementation and the manifest for our plugin – plugin.xml.

Note

To use Java in your plugin, create the /src/main/java directory.

The plugin logo is placed in src/main/resources/META-INF/pluginIcon.svg. See Plugin Logo for more information and logo requirements.

Build script

The build.gradle.kts is the core of the project definition. It applies three Gradle plugins:

Plugin	Description
org.jetbrains.kotlin.jvm	Adds Kotlin support
org.jetbrains.changelog	Simplifies patching the CHANGELOG.md file
org.jetbrains.intellij.platform	The IntelliJ Platform Gradle Plugin

The intellijPlatform dependencies block selects the IDE to compile against:

intellijIdea("2026.1.5")

See Target Versions for more information.

This project currently has no automated test sources, so it intentionally does not declare the IntelliJ Platform test framework. The standard test task remains usable and reports NO-SOURCE until tests are added.

Plugin configuration file

The plugin configuration file is a plugin.xml file located in the src/main/resources/META-INF directory. It provides general information about the plugin, its dependencies, extensions, and listeners.

You can read more about this file in the Plugin Configuration File section of our documentation.

Plugin ID and name

Generated plugin ID and name may require adjustment.

These values are generated based on Group ID and Artifact ID provided in the IDE Plugin wizard. It is recommended to review <id> and <name> elements in the plugin.xml file, and adjust them if needed.

Please note that Gradle properties rootProject.name and project.group don't need to match the <id> and <name> elements. There is no IntelliJ Platform-related reason they should as they serve different functions.

Predefined Run/Debug configurations

Within the default project structure, there is a .run directory provided containing predefined Run/Debug configurations that expose corresponding Gradle tasks:

Configuration name	Description
Run IDE with Plugin	Runs :runIde IntelliJ Platform Gradle Plugin task. Use the Debug icon for plugin debugging.
Run Validation	Runs :check. The test task reports NO-SOURCE until automated tests are added.
Run Verifications	Runs :verifyPlugin IntelliJ Platform Gradle Plugin task to check the plugin compatibility against the specified IntelliJ IDEs.

Note

You can find the logs from the running task in the idea.log tab.

Publishing the plugin

Tip

Make sure to follow all guidelines listed in Publishing a Plugin to follow all recommended and required steps.

Releasing a plugin to JetBrains Marketplace is a straightforward operation that uses the publishPlugin Gradle task provided by the intellij-platform-gradle-plugin.

You can also upload the plugin to the JetBrains Plugin Repository manually via UI.

GitHub Integration

GitHub Actions

The project includes [GitHub Actions][https://docs.github.com/en/actions] workflows for automated CI/CD:

Workflow	Trigger	Description
Build	Push / PR	Builds, validates, and verifies the plugin; creates a draft release
Release	GitHub Release	Publishes the plugin to JetBrains Marketplace

GitHub issue templates

The project includes GitHub issue templates:

• Bug Report
• Feature Request

See Syntax for issue forms.

Dependabot

Dependabot configuration file enables tracking outdated or vulnerable dependencies.

Useful links

• IntelliJ Platform SDK Plugin SDK
• IntelliJ Platform Gradle Plugin Documentation
• IntelliJ Platform Explorer
• JetBrains Marketplace Quality Guidelines
• IntelliJ Platform UI Guidelines
• JetBrains Marketplace Paid Plugins
• IntelliJ SDK Code Samples