Skip to content

Commit f05bc64

Browse files
docs: add plugin-focused CONTRIBUTING.md guide (#1533)
1 parent e394eea commit f05bc64

1 file changed

Lines changed: 47 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
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

Comments
 (0)