1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
---
title: Your first plugin
permalink: /docs/plugins/your-first-plugin/
---
Plugins allow you to extend Jekyll's behavior to fit your needs. There are six
types of plugins in Jekyll.
## Generators
[Generators](/docs/plugins/generators/) create content on your site.
For example:
* [jekyll-feed](https://github.com/jekyll/jekyll-feed) creates an Atom feed of
blog posts.
* [jekyll-archives](https://github.com/jekyll/jekyll-archives) creates archive
pages for blog categories and tags.
* [jekyll-sitemap](https://github.com/jekyll/jekyll-sitemap) creates a sitemap.
## Converters
[Converters](/docs/plugins/converters/) change a markup language into another
format. For example:
* [jekyll-textile-converter](https://github.com/jekyll/jekyll-textile-converter)
converts textile to HTML.
* [jekyll-coffeescript](https://github.com/jekyll/jekyll-coffeescript) converts
Coffeescript to JavaScript.
* [jekyll-opal](https://github.com/jekyll/jekyll-opal) converts Ruby to
JavaScript.
## Commands
[Commands](/docs/plugins/commands/) extend the `jekyll` executable with
subcommands. For example:
* [jekyll-compose](https://github.com/jekyll/jekyll-compose) adds subcommands
for creating a post, page or draft.
## Tags
[Tags](/docs/plugins/tags/) create custom Liquid tags. For example:
* [jekyll-youtube](https://github.com/dommmel/jekyll-youtube) embeds a YouTube
video.
* [jekyll-asset-path-plugin](https://github.com/samrayner/jekyll-asset-path-plugin)
outputs a relative URL for assets.
* [jekyll-swfobject](https://github.com/sectore/jekyll-swfobject) embeds a SWF
object.
## Filters
[Filters](/docs/plugins/filters/) create custom Liquid filters. For example:
* [jekyll-time-ago](https://github.com/markets/jekyll-timeago) - The distance
between two dates in words.
* [jekyll-toc](https://github.com/toshimaru/jekyll-toc) - Generates a table of
content.
* [jekyll-email-protect](https://github.com/vwochnik/jekyll-email-protect) -
Obfuscates emails to protect them from spam bots.
## Hooks
[Hooks](/docs/plugins/hooks/) give fine-grained control to extend the build
process. For example:
* [jemoji](https://github.com/jekyll/jemoji) Display emojis :+1:
* [jekyll-mentions](https://github.com/jekyll/jekyll-mentions) turns mentions @jekyll into links
* [jekyll-spaceship](https://github.com/jeffreytse/jekyll-spaceship) - advanced example. Provides
powerful supports for table, mathjax, plantuml, video, etc.
## Flags
There are two flags to be aware of when writing a plugin:
<div class="mobile-side-scroller">
<table>
<thead>
<tr>
<th>Flag</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<p><code>safe</code></p>
</td>
<td>
<p>
A boolean flag that informs Jekyll whether this plugin may be safely
executed in an environment where arbitrary code execution is not
allowed. This is used by GitHub Pages to determine which core plugins
may be used, and which are unsafe to run. If your plugin does not
allow for arbitrary code execution, set this to <code>true</code>.
GitHub Pages still won’t load your plugin, but if you submit it for
inclusion in core, it’s best for this to be correct!
</p>
</td>
</tr>
<tr>
<td>
<p><code>priority</code></p>
</td>
<td>
<p>
This flag determines what order the plugin is loaded in. Valid values
are: <code>:lowest</code>, <code>:low</code>, <code>:normal</code>,
<code>:high</code>, and <code>:highest</code>. Highest priority
matches are applied first, lowest priority are applied last.
</p>
</td>
</tr>
</tbody>
</table>
</div>
To use one of the example plugins above as an illustration, here is how you’d
specify these two flags:
```ruby
module Jekyll
class UpcaseConverter < Converter
safe true
priority :low
...
end
end
```
## Best Practices
The guides help you with the specifics of creating plugins. We also have some
recommended best practices to help structure your plugin.
We recommend using a [gem](/docs/ruby-101/#gems) for your plugin. This will
help you manage dependencies, keep separation from your site source code and
allow you to share functionality across multiple projects. For tips on creating
a gem take a look at the
[Ruby gems guide](https://guides.rubygems.org/make-your-own-gem/) or look
through the source code of an existing plugin such as
[jekyll-feed](https://github.com/jekyll/jekyll-feed).
|
