|
| 1 | +# Contributing to PrismJS |
| 2 | + |
| 3 | +First off, thank you for considering contributing to PrismJS! It's people like you that make Prism such a great tool. |
| 4 | + |
| 5 | +This guide will help you understand how Prism works under the hood and how you can add new plugins to extend its functionality. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 1. How Prism Works |
| 10 | + |
| 11 | +At its core, Prism is a lightweight, regex-based syntax highlighter. It works by taking a string of code and a "Grammar" (a collection of regular expressions), and breaking the code down into an array of tokens (like `keyword`, `string`, `function`, etc.). These tokens are then wrapped in HTML `<span>` elements with specific CSS classes, which are styled by Prism's themes. |
| 12 | + |
| 13 | +**The core components are:** |
| 14 | +* **`Prism.core.js`**: The main engine that handles tokenization and hooks. |
| 15 | +* **Grammars**: Objects containing regular expressions that define a language's syntax. |
| 16 | +* **Hooks**: Prism provides a callback architecture (`Prism.hooks`) that allows plugins to modify the core behavior without changing the core code. |
| 17 | + |
| 18 | +--- |
| 19 | + |
| 20 | +## 2. Writing a New Plugin |
| 21 | + |
| 22 | +We highly encourage developers to build plugins to extend Prism's functionality beyond basic syntax highlighting (e.g., line numbers, show invisibles, etc.). |
| 23 | + |
| 24 | +Since Prism relies heavily on its hook system, plugins are written by tapping into these hooks rather than modifying the core engine. |
| 25 | + |
| 26 | +1. **Create the directory**: Create a new folder in `plugins/` named `your-plugin-name`. |
| 27 | +2. **Create the files**: Create `prism-your-plugin-name.js` and (if needed) `prism-your-plugin-name.css`. |
| 28 | +3. **Use Hooks**: Hook into Prism's execution lifecycle to modify the DOM or the token stream. |
| 29 | +```javascript |
| 30 | + Prism.hooks.add('complete', function (env) { |
| 31 | + // Your plugin logic here |
| 32 | + // 'env' contains the code, grammar, language, and the DOM element |
| 33 | + }); |
| 34 | +Register the Plugin: Make sure to add your new plugin to components.json or the relevant build configuration so the build system recognizes it and can generate the necessary bundles. |
| 35 | + |
| 36 | +3. Submitting your Pull Request |
| 37 | +Fork the repository and create your branch from master. |
| 38 | + |
| 39 | +Run npm install to get everything set up. |
| 40 | + |
| 41 | +Make your plugin additions. |
| 42 | + |
| 43 | +Run npm test and ensure all tests pass (Prism uses standard Mocha tests). |
| 44 | + |
| 45 | +Commit your changes with a clear and descriptive commit message. |
| 46 | + |
| 47 | +Open a Pull Request! Please include a summary of your changes and reference the issue number if applicable. |
0 commit comments