92 lines
2.3 KiB
Markdown
92 lines
2.3 KiB
Markdown
---
|
||
title: Converters
|
||
permalink: /docs/plugins/converters/
|
||
---
|
||
|
||
If you have a new markup language you’d like to use with your site, you can
|
||
include it by implementing your own converter. Both the Markdown and
|
||
[Textile](https://github.com/jekyll/jekyll-textile-converter) markup
|
||
languages are implemented using this method.
|
||
|
||
<div class="note info">
|
||
<h5>Remember your Front Matter</h5>
|
||
<p>
|
||
Jekyll will only convert files that have a YAML header at the top, even for
|
||
converters you add using a plugin.
|
||
</p>
|
||
</div>
|
||
|
||
Below is a converter that will take all posts ending in `.upcase` and process
|
||
them using the `UpcaseConverter`:
|
||
|
||
```ruby
|
||
module Jekyll
|
||
class UpcaseConverter < Converter
|
||
safe true
|
||
priority :low
|
||
|
||
def matches(ext)
|
||
ext =~ /^\.upcase$/i
|
||
end
|
||
|
||
def output_ext(ext)
|
||
".html"
|
||
end
|
||
|
||
def convert(content)
|
||
content.upcase
|
||
end
|
||
end
|
||
end
|
||
```
|
||
|
||
Converters should implement at a minimum 3 methods:
|
||
|
||
<div class="mobile-side-scroller">
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Method</th>
|
||
<th>Description</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>
|
||
<p><code>matches</code></p>
|
||
</td>
|
||
<td><p>
|
||
Does the given extension match this converter’s list of acceptable
|
||
extensions? Takes one argument: the file’s extension (including the
|
||
dot). Must return <code>true</code> if it matches, <code>false</code>
|
||
otherwise.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p><code>output_ext</code></p>
|
||
</td>
|
||
<td><p>
|
||
The extension to be given to the output file (including the dot).
|
||
Usually this will be <code>".html"</code>.
|
||
</p></td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<p><code>convert</code></p>
|
||
</td>
|
||
<td><p>
|
||
Logic to do the content conversion. Takes one argument: the raw content
|
||
of the file (without front matter). Must return a String.
|
||
</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
|
||
In our example, `UpcaseConverter#matches` checks if our filename extension is
|
||
`.upcase`, and will render using the converter if it is. It will call
|
||
`UpcaseConverter#convert` to process the content. In our simple converter we’re
|
||
simply uppercasing the entire content string. Finally, when it saves the page,
|
||
it will do so with a `.html` extension.
|