|
1 |
| -## Eleventy Plugin Template |
| 1 | +# eleventy-plugin-torchlight |
2 | 2 |
|
3 |
| -> A starter environment for creating plugins for Eleventy (11ty). |
| 3 | +This is a plugin for the static site generator [Eleventy](https://11ty.dev) to syntax highlight your code blocks with [torchlight.dev](https://torchlight.dev). |
4 | 4 |
|
5 |
| -Fork this repo, or select "Use this template" to get started. |
| 5 | +## Prerequisites |
6 | 6 |
|
7 |
| -### Using this template |
| 7 | +To use this plugin you need to be registered on [torchlight.dev](https://torchlight.dev) and have obtained an API key. |
8 | 8 |
|
9 |
| -This template is setup to run a single page 11ty site for testing your plugin functionality. The build files are excluded from the final plugin package via `.npmignore`. |
| 9 | +## Installation |
10 | 10 |
|
11 |
| -Your plugin functionality should live in/be exported from `.eleventy.js`. You will find a sample of creating a filter plugin in this template, including setting up a default config and merging user options. |
12 |
| - |
13 |
| -**Be sure to update the `package.json` with your own details!** |
14 |
| - |
15 |
| -### Testing your plugin |
16 |
| - |
17 |
| -You can test your functionality within this project's local 11ty build by running `npm start`, but you'll also want to test it _as a plugin_. |
18 |
| - |
19 |
| -From another local 11ty project, you can set the `require()` path relatively to your plugin's project directory, and then use it just as you would for a plugin coming from a package. |
| 11 | +```bash |
| 12 | +npm install eleventy-plugin-torchlight #or |
| 13 | +yarn add eleventy-plugin-torchlight |
| 14 | +``` |
20 | 15 |
|
21 |
| -Example, assuming you place all your repositories within the same parent directory: |
| 16 | +Then, include it in your `.eleventy.js` config file: |
22 | 17 |
|
23 | 18 | ```js
|
24 |
| -const pluginName = require("../plugin-directory"); |
| 19 | +const torchlight = require('eleventy-plugin-torchlight'); |
25 | 20 |
|
26 | 21 | module.exports = (eleventyConfig) => {
|
27 |
| - eleventyConfig.addPlugin(pluginName, { optionName: 'if needed' ); |
| 22 | + eleventyConfig.addPlugin(torchlight); |
28 | 23 | };
|
29 | 24 | ```
|
30 | 25 |
|
31 |
| -Then, run the project to test the plugin's functionality. |
32 |
| -
|
33 |
| -Note that making changes in the plugin source will likely require restarting the test project. |
34 |
| -
|
35 |
| -### Resources for creating an 11ty plugin |
36 |
| -
|
37 |
| -- Bryan Robinson's ["Create a Plugin with 11ty"](https://www.youtube.com/watch?v=aO-NFFKjnnE) demonstration on "Learn With Jason" |
38 |
| -
|
39 |
| ---- |
| 26 | +## Configuration |
40 | 27 |
|
41 |
| -**The following is a boilerplate for your final plugin README**. |
| 28 | +Run `npx torchlight init` to initialize a default torchlight config. If you don't create a config yourself this plugin assumes this defaults to match 11ty's |
| 29 | +defaults: |
42 | 30 |
|
43 |
| -## Usage |
44 |
| -
|
45 |
| -Describe how to install your plugin, such as: |
46 |
| -
|
47 |
| -```bash |
48 |
| -npm install @scope/plugin-name |
| 31 | +``` |
| 32 | +{ |
| 33 | + token: process.env.TORCHLIGHT_TOKEN, |
| 34 | + highlight: { |
| 35 | + input: '_site' |
| 36 | + } |
| 37 | +} |
49 | 38 | ```
|
50 | 39 |
|
51 |
| -Then, include it in your `.eleventy.js` config file: |
| 40 | +> If you create a new config remember to update the config to match the input path of Eleventy! |
52 | 41 |
|
53 |
| -```js |
54 |
| -const pluginName = require("@scope/plugin-name"); |
| 42 | +To verify everything works you can run Eleventy like this to pass the token as environment variable: |
55 | 43 |
|
56 |
| -module.exports = (eleventyConfig) => { |
57 |
| - eleventyConfig.addPlugin(pluginName); |
58 |
| -}; |
59 | 44 | ```
|
| 45 | +`TORCHLIGHT_TOKEN=your_token npm run start` |
| 46 | +``` |
| 47 | + |
| 48 | +Your code should now be highlighted. |
60 | 49 |
|
61 |
| -## Config Options |
| 50 | +If you are for example using Netflify you can add the token via your site's settings so it's available during the build. |
62 | 51 |
|
63 |
| -| Option | Type | Default | |
64 |
| -| ----------- | ---- | ------------- | |
65 |
| -| option name | type | default value | |
| 52 | +### Cache |
66 | 53 |
|
67 |
| -## Config Examples |
| 54 | +Torchlight uses a cache to prevent highlighting code blocks that don't have changed. |
| 55 | +By default it uses a [file based cache](https://torchlight.dev/docs/clients/cli#cache) which created a directory called `cache`. |
68 | 56 |
|
69 |
| -Show examples of likely configurations. |
| 57 | +Make sure you add this folder to your `.eleventyignore` file so it doesn't trigger rebuilds after highlighting your output files. |
70 | 58 |
|
71 | 59 | ## Credits
|
72 | 60 |
|
73 |
| -Add credits if needed. |
| 61 | +Thanks to [@5t3ph](https://twitter.com/5t3ph) for her [eleventy-plugin-template](https://github.com/5t3ph/eleventy-plugin-template) |
| 62 | +and [Aaron Francis](https://twitter.com/aarondfrancis) for [Torchlight](https://torchlight.dev). |
0 commit comments