Add search bar and minor github/contributing improvements

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+    "MD024": false,
+    "MD013": false
+}

.prettierrc.json

@@ -0,0 +1,14 @@
+{
+    "tabWidth": 2,
+    "useTabs": false,
+    "singleQuote": false,
+    "plugins": ["prettier-plugin-vitepress"],
+    "overrides": [
+        {
+            "files": [".*md"],
+            "options": {
+                "parser": "markdown"
+            }
+        }
+    ]
+}

.vitepress/config.mts

@@ -23,7 +23,9 @@ export default defineConfig({
             {text: 'Development', link: '/development/building-and-running'},
             {text: 'Plugins', link: '/plugins/'}
         ],
-
+        search: {
+            provider: 'local'
+        },
         sidebar: [
             {
                 text: 'Tutorials',

.vitepress/theme/custom.css

@@ -1,18 +1,18 @@
 /* Light Mode */
 
 :root {
-    --vp-button-alt-bg: #e3e6ed;
+    --vp-button-alt-bg: #e3e6ed; /* Make secondary button background not blend in */
 }
 
 .VPNavBar {
-    border-bottom: 2px solid #d2d5dc;
-    background-color: #e6e9ef;
+    border-bottom: 2px solid #d2d5dc; /* Border for navbar */
+    background-color: #e6e9ef; /* Distinguish between nav bar and main page content */
 }
 
 /* Dark Mode */
 
 .dark {
-    --vp-button-alt-bg: #353552; /* Make front page secondary button background not blend in with background*/
+    --vp-button-alt-bg: #353552; /* Make secondary button background not blend in with background*/
 }
 
 .dark .VPNavBar {

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to RailroadDocs
+
+By contributing code to the RailroadDocs repository, you:
+
+- Own all the rights to the code in your pull request
+- Consent to the publishing of your code publicly
+
+## How to start contributing
+
+### Use a personal fork, not an Organization
+
+We may modify your pull request for you, rather than requesting you to make the changes yourself, for efficiency purposes. However, if your fork is hosted on an Organization, we cannot make such changes, so we request that you use a personal fork in your pull requests.
+
+### Requirements
+
+To start adding your content to RailroadDocs, you will need the following software:
+
+- A nodejs version manager
+- NPM
+
+Once you have those installed, install the required dependencies with `npm i`, then you may run the dev server by executing: `npm run dev` in the root of the project.
+You will then be given a url to follow to view your locally hosted instance of RailroadDocs.
+
+### Pull Request Requirements
+
+We don't want to waste your or our time on pull requests that just can't be justified. Hence these guidelines each and every pull request must adhere to.
+
+- You must be able to justify the pull request.
+
+  It must fulfill at least one of these requirements:
+  - Add undocumented feature(s) to the site, to aid developers who may want to learn about such feature(s).
+  - Fix errors or mistakes in existing files.
+  - Clarify or rewrite existing documents to provide an easier and clearer experience for any readers.
+  - Improve the experience of any reader.
+- All additions must be written in English, alongside any other language you can provide accurate translations for.
+- All modified files must adhere to our Formatting Guide.
+- All content must be PG.
+- Any and all content, including translations, must be created by a human.
+- At the point of review, the pull request must be up to date with the latest version of the base branch.
+
+### Formatting Guidelines
+
+We want to make sure that all content added is of a same standard to any other piece, so please keep these guidelines in mind at all times.
+We suggest installing the markdownlint plugin, as it comes with a good set of guidelines for formatting markdown files.
+
+- Headers must be used in ascending order.
+- All sentences must end in a full stop.
+- Any references to class names or methods must be surrounded using "`".
+- All code snippets must be in code blocks, which are created using "\`\`\`java --code here --\`\`\`"
+- Any API feature page must have an accurate and descriptive example

README.md

@@ -0,0 +1,12 @@
+# Railroad Docs
+
+![Static Badge](https://img.shields.io/badge/nodejs-24.3.0-brightgreen?logo=nodedotjs&label=NodeJS)
+![Static Badge](https://img.shields.io/badge/Vitepress-1.6.3-brightgreen?logo=vitepress&label=Vitepress)
+
+This is the repository that hosts the source code for the <https://railroadide.dev/> website.
+
+## Theming
+
+The website uses the [Catppuccin Mocha Sapphire](https://github.com/catppuccin/vitepress) theme, with some additional custom css.
+
+If you want to contribute, please read our [Contributing Guide](CONTRIBUTING.md).

src/development/building-and-running.md

@@ -19,12 +19,14 @@ Before you begin, ensure you have the following installed on your system:
    - Restart IntelliJ when prompted
 
 2. **Clone the Repository**:
+
    ```bash
    git clone https://github.com/Railroad-Team/Railroad.git
    cd Railroad
    ```
 
 3. **Update Submodules**:
+
    ```bash
    git submodule update --init --recursive
    ```
@@ -49,12 +51,15 @@ Before you begin, ensure you have the following installed on your system:
 ### Using Gradle Wrapper
 
 1. **Build the project**:
+
    ```bash
    ./gradlew build
    ```
+
    (On Windows, use `gradlew.bat` instead of `./gradlew`)
 
 2. **Run the application**:
+
    ```bash
    ./gradlew run
    ```

src/plugins/api-reference/events.md

@@ -10,7 +10,7 @@ This is the base interface for all events in the Railroad system. All custom eve
 
 The `EventBus` is the central component for the event system. It allows plugins to publish new events and subscribe to existing ones. You can obtain an instance of the `EventBus` from the `PluginContext`.
 
-### Methods:
+### Methods
 
 - `void publish(Event event)`: Publishes an event to the bus, notifying all subscribed listeners.
 - `void subscribe(Class<T> eventType, EventListener<T> listener)`: Subscribes a given `EventListener` to events of a specific type.
@@ -20,7 +20,7 @@ The `EventBus` is the central component for the event system. It allows plugins
 
 This interface is used to define a callback for handling events. When an event of the type `T` (which extends `Event`) is published, the `handle` method of the `EventListener` will be invoked.
 
-### Methods:
+### Methods
 
 - `void handle(T event)`: This method is called when an event of type `T` is published.
 
@@ -63,4 +63,4 @@ public class ProjectLoggerPlugin implements Plugin {
         // if the plugin context handles their lifecycle.
     }
 }
-```
+```

src/plugins/api-reference/gson-locator.md

@@ -6,7 +6,7 @@ The Railroad Plugin API provides a centralized way to access a pre-configured `G
 
 The `GsonLocator` is a utility class that provides a singleton instance of `com.google.gson.Gson`. Plugins should use this locator to obtain the `Gson` instance for their JSON operations.
 
-### Key Methods:
+### Key Methods
 
 - `static Gson getInstance()`: Retrieves the singleton `Gson` instance. Throws `IllegalStateException` if the `Gson` instance has not been set (which is typically handled by the core application during startup).
 
@@ -50,5 +50,3 @@ public class MyGsonPlugin implements Plugin {
     }
 }
 ```
-
-```

src/plugins/api-reference/index.md

@@ -2,7 +2,7 @@
 
 This section provides a detailed reference for the Railroad Plugin API, covering core components, event handling, services, registries, settings, localization, secure storage, Gson utilities, JSON serialization, and UI components.
 
-## Topics:
+## Topics
 
 - [Plugin Lifecycle and Context](./plugin.md)
 - [Events](./events.md)

src/plugins/api-reference/localization.md

@@ -6,7 +6,7 @@ The Railroad Plugin API provides a localization system to help plugins support m
 
 The `LocalizationService` interface provides methods for retrieving localized strings based on a key and optional arguments. This allows your plugin to display messages, UI elements, and other text in the user's preferred language.
 
-### Key Methods:
+### Key Methods
 
 - `String get(String key)`: Retrieves the localized string for the given key.
 - `String get(String key, Object... args)`: Retrieves the localized string for the given key, replacing placeholders with the provided arguments.
@@ -51,7 +51,7 @@ Translations are stored in `.lang` files, which are simple key-value pair files.
 
 For example, an English (US) language file would be named `en_us.lang`.
 
-### Format:
+### Format
 
 Each line in a `.lang` file represents a key-value pair, where the key is used to retrieve the localized string, and the value is the translated text. Comments can be added using `#`.
 
@@ -65,10 +65,10 @@ settings.myplugin.enable_feature.title=Enable My Feature
 settings.myplugin.enable_feature.description=Toggles the main feature of my plugin.
 ```
 
-### Placeholders:
+### Placeholders
 
 Placeholders in the translated strings are denoted by `%s`, `%d`, etc., similar to `String.format()` in Java, corresponding to the order of arguments passed to the `localizationService.get()` method.
 
 For instance, in `Hello, %s!`, `%s` will be replaced by the first string argument provided.
 
-By organizing your translations in these `.lang` files, the `LocalizationService` can automatically load the appropriate language based on the application's current locale, providing a seamless localized experience for your users.
+By organizing your translations in these `.lang` files, the `LocalizationService` can automatically load the appropriate language based on the application's current locale, providing a seamless localized experience for your users.

src/plugins/api-reference/logger.md

@@ -139,4 +139,4 @@ if (currentLevel.ordinal() <= LoggingLevel.WARN.ordinal()) {
 - **Log Archiving**: Existing log files are archived (copied and potentially compressed) before new logging sessions begin.
 - **Log Deletion**: Old log files are periodically deleted based on the `deletionFrequency` configured for each logger.
 
-These operations are managed internally and do not require direct interaction from plugins.
+These operations are managed internally and do not require direct interaction from plugins.

src/plugins/api-reference/plugin.md

@@ -6,7 +6,7 @@ These are the core components for creating a plugin in Railroad.
 
 This is the main interface that your plugin class must implement. It defines the lifecycle methods that the Railroad application will call when your plugin is loaded and unloaded.
 
-### Methods:
+### Methods
 
 - `void onEnable(PluginContext context)`: Called when your plugin is enabled. This is the primary entry point for your plugin's logic. You receive a `PluginContext` object which provides access to various application services and functionalities.
 - `void onDisable(PluginContext context)`: Called when your plugin is disabled. Use this method to clean up any resources, unregister listeners, or save state before your plugin is unloaded.
@@ -15,7 +15,7 @@ This is the main interface that your plugin class must implement. It defines the
 
 The `PluginContext` interface provides your plugin with access to the Railroad application's core services, event bus, logger, and other essential functionalities. An instance of `PluginContext` is passed to your plugin's `onEnable` and `onDisable` methods.
 
-### Key Methods:
+### Key Methods
 
 - `PluginDescriptor getDescriptor()`: Returns the descriptor of the plugin, containing metadata like name, version, and description.
 - `EventBus getEventBus()`: Provides access to the application's event bus, allowing your plugin to publish and subscribe to events.
@@ -31,5 +31,3 @@ The `PluginContext` interface provides your plugin with access to the Railroad a
 ## `PluginDescriptor`
 
 This interface describes your plugin and contains metadata such as its name, version, and description. This information is typically loaded from a plugin configuration file (e.g., `plugin.json`).
-
-

src/plugins/api-reference/registries.md

@@ -66,7 +66,7 @@ public class MySettingPlugin implements Plugin {
 
 The `dev.railroadide.core.registry.Registry` interface defines the common operations for managing collections of items. Any registry you obtain from the `PluginContext` or `Registries` utility class will implement this interface.
 
-### Key Methods:
+### Key Methods
 
 - `String getId()`: Returns the unique identifier of the registry.
 - `Type getType()`: Returns the generic type of items managed by the registry.
@@ -132,4 +132,4 @@ public class MyGenericRegistryPlugin implements Plugin {
         // Clean up
     }
 }
-```
+```

src/plugins/api-reference/secure-storage.md

@@ -6,7 +6,7 @@ The Railroad Plugin API provides a `SecureTokenStore` for securely storing sensi
 
 The `SecureTokenStore` class allows you to save, retrieve, and clear tokens securely. It typically uses platform-specific mechanisms (e.g., OS keychain, encrypted files) to protect the data.
 
-### Key Methods:
+### Key Methods
 
 - `SecureTokenStore(String serviceName)`: Constructor. `serviceName` is a unique identifier for your plugin's storage area.
 - `void saveToken(String token, String key)`: Saves a token associated with a given key.

src/plugins/api-reference/services.md

@@ -98,4 +98,4 @@ public class MyVCSPlugin implements Plugin {
         // Clean up resources if necessary
     }
 }
-```
+```

src/plugins/api-reference/settings.md

@@ -6,7 +6,7 @@ The Railroad Plugin API provides a robust system for defining, managing, and per
 
 The `Setting` class is the core component of the settings API. Each `Setting` represents a single configurable value within the application. Settings are typically registered with the settings registry and can be accessed and modified by plugins.
 
-### Key Properties:
+### Key Properties
 
 - `id` (String): A unique identifier for the setting (e.g., `myplugin:my_setting_id`).
 - `treePath` (String): Defines the hierarchical path for the setting, used for organizing settings in the UI (e.g., `plugins.myplugin.general`).
@@ -17,7 +17,7 @@ The `Setting` class is the core component of the settings API. Each `Setting` re
 - `description` (String): A descriptive text providing more information about the setting.
 - `codec` (SettingCodec<T, ?>): Defines how the setting's value is serialized/deserialized and how it interacts with UI components.
 
-### Building a Setting:
+### Building a Setting
 
 You create `Setting` instances using its fluent `builder` API:
 
@@ -51,7 +51,7 @@ Setting<String> customMessageSetting = Setting.builder(String.class, "myplugin:c
 
 `SettingCategory` is used to group related settings together, primarily for organizing them within the application's user interface. Each category has an `id`, `title`, and `description`.
 
-### Building a SettingCategory:
+### Building a SettingCategory
 
 ```java
 import dev.railroadide.core.settings.SettingCategory;
@@ -70,7 +70,7 @@ SettingCategory advancedCategory = SettingCategory.builder("myplugin:advanced")
 
 A `SettingCodec` defines how a setting's value is converted between its Java object representation, its JSON representation (for persistence), and its UI component representation (e.g., a `TextField` for a `String`).
 
-### Key Components:
+### Key Components
 
 - `nodeToValue`: Function to extract the value from a UI Node.
 - `valueToNode`: Function to set the value in a UI Node.
@@ -84,7 +84,7 @@ Plugins can create custom codecs for complex data types or custom UI components.
 
 Railroad provides a set of predefined `SettingCodec` instances for common data types, making it easy to create settings for basic types without defining custom codecs. These are available through `DefaultSettingCodecs`.
 
-### Available Default Codecs:
+### Available Default Codecs
 
 - `BOOLEAN` (for `Boolean` values, uses `CheckBox`)
 - `STRING` (for `String` values, uses `TextField`)
@@ -93,7 +93,7 @@ Railroad provides a set of predefined `SettingCodec` instances for common data t
 - `FLOAT` (for `Float` values, uses `TextField`)
 - `LONG` (for `Long` values, uses `TextField`)
 
-### Example Usage:
+### Example Usage
 
 ```java
 import dev.railroadide.core.settings.DefaultSettingCodecs;

src/plugins/api-reference/ui/browse-button.md

@@ -19,12 +19,12 @@
 ## Enums
 
 - `BrowseType`: Defines the type of browsing operation:
-    - `FILE`: For selecting files.
-    - `DIRECTORY`: For selecting directories.
-    - `IMAGE`: For selecting image files (with predefined filters).
+  - `FILE`: For selecting files.
+  - `DIRECTORY`: For selecting directories.
+  - `IMAGE`: For selecting image files (with predefined filters).
 - `BrowseSelectionMode`: Defines the selection mode:
-    - `SINGLE`: Allows selecting only one item.
-    - `MULTIPLE`: Allows selecting multiple items.
+  - `SINGLE`: Allows selecting only one item.
+  - `MULTIPLE`: Allows selecting multiple items.
 
 ## Usage Example
 

src/plugins/api-reference/ui/forms/form-directory-chooser.md

@@ -35,5 +35,3 @@ Constructs a new `TextFieldWithButton`.
 
 - `textField`: The text field for displaying the selected directory path.
 - `browseButton`: The browse button for opening the directory chooser, or `null` if not needed.
-
-```

src/plugins/api-reference/ui/rr-card.md

@@ -50,4 +50,4 @@ card.setInteractive(true);
 card.setOnMouseClicked(event -> {
     System.out.println("Card clicked!");
 });
-```
+```

src/plugins/api-reference/ui/rr-form-container-section.md

@@ -75,4 +75,4 @@ advancedSection.addContent(
     new RRButton("myplugin.button.apply")
 );
 formContainer.addSection(advancedSection);
-```
+```

src/plugins/api-reference/ui/rr-grid-pane.md

@@ -25,4 +25,4 @@ gridPane.setPadding(new Insets(10));
 gridPane.add(new RRTextField("myplugin.textfield.placeholder.firstname"), 0, 0); // (column, row)
 gridPane.add(new RRTextField("myplugin.textfield.placeholder.lastname"), 1, 0);
 gridPane.add(new RRButton("myplugin.button.save"), 0, 1, 2, 1); // (column, row, columnspan, rowspan)
-```
+```