sublime-jekyll¶
sublime-jekyll is a Sublime Text package for Jekyll static sites. This package is aimed at streamlining the process of managing and creating new Jekyll posts. It does this by providing quick and easy access to new post and draft commands, snippets and completions for Liquid template tags and filters, as well as some handy commands for adding dates and upload links to your posts.
If you use Jekyll as your static site generator, and Sublime Text as your text editor, you should absolutely install and use this package!
What’s New in v3.0?¶
Installation¶
Package Control¶
The recommended way to install and update this package is using Package Control from wbond.net. Search for Jekyll and install the latest version.
- Press
Ctrl + Shift + P
(Windows/Linux) orCommand + Shift + P
(OS X) to bring up the Command Palette (or use the Tools > Command Palette menu) - Search for the Package Control: Install Package command
- Search packages for Jekyll and hit
Enter
to install the latest version
Manual¶
If you would prefer to install this package manually, you can do that directly from GitHub.
Make sure the contents of the repo resides in your Sublime Text Packages folder. You can usually find this under Preferences > Browse Packages…. If not, try looking in one of these places (based on your platform).
- OS X:
~/Library/Application\ Support/Sublime\ Text\ 3/Packages
- Windows:
%APPDATA%\Sublime Text 3\Packages
- Linux:
~/.config/sublime-text-3/Packages
Settings¶
sublime-jekyll ships with a number of configurable settings. These can be overridden globally in your User Settings file, or on a per-Project basis using the recommended Project Settings syntax.
Warning
sublime-jekyll settings prior to v3.0 have been deprecated!
We know that is a bit of a pain - we get it - but it was for the best moving forward.
To help with the transition, we have created some Jekyll Utility commands that automatically migrate your old, deprecated settings to new, fully supported settings. You can find these in the Command Palatte by searching for Jekyll Utility.
User Settings¶
Warning
Unless otherwise stated, all path strings should be absolute paths, not relative paths!
Also, path strings should follow your system-specific path convention. For example, Windows machines should have a path similar to C:\\Users\\username\\site\\_posts
, while Unix/Linux systems should have a path similar to /Users/username/site/_posts
.
jekyll_posts_path
¶
Default: None Description: This should point to your _posts
directory.
jekyll_drafts_path
¶
Default: None Description: This should point to your _drafts
directory.
jekyll_templates_path
¶
Default: None (if left blank, User/Jekyll Templates
will be used as a fallback)Description: This should point to your _templates
directory.
jekyll_auto_find_paths
¶
Default: false
Description: If you don’t want to hard-code your _posts
,_drafts
,uploads
, or_templates
paths into your settings file, you can optionally have sublime-jekyll look for_posts
,_drafts
,uploads
, and/or_templates
folders open in your sidebar. If you don’t name the folders appropriately, or you use a non-standard file structure for your Jekyll project, you have a higher chance of returning path exception errors. This should have a value oftrue
orfalse
.
jekyll_uploads_path
¶
Default: None Description: This should point to your uploads
directory.
jekyll_uploads_baseurl
¶
Default: {{ site.baseurl }}
Description: This string value should represent the baseurl for the uploads directory. For example, if your uploads directory is uploads
and you have an image calledimage.png
, the output of inserting the image in your post would be{{ uploads_baseurl }}/uploads/image.png
, with{{ uploads_baseurl }}
replace by its value.
Note
If you wish to have an absolute link and you have url
defined in your Jekyll config.yml
file, then you can set the value to {{ site.url }}/{{ site.baseurl }}
.
jekyll_default_markup
¶
Default: Markdown
Description: This string value determines the file type for new drafts and posts. It can be set to one of three accepted values: Markdown
,Textile
,HTML
, orPlain text
.
jekyll_markdown_extension
¶
Default: markdown
Description: Optionally override the file extension format for Markdown files. Valid options include: markdown
,mdown
,mkdn
,mkd
,md
. Do not include the dot in your string value.
Note
We use .markdown
as the standard file extension for Markdown files as suggested by John Gruber, developer of Markdown, in his blog post here: http://daringfireball.net/linked/2014/01/08/markdown-extension.
jekyll_send_to_trash
¶
Default: false
Description: Determines if sublime-jekyll should send deleted drafts, posts and templates to the system trash/recycling bin, or immediately purge them from disk.
jekyll_date_format
¶
Default: %Y-%m-%d
Description: A valid Python strftime string for a date.
jekyll_datetime_format
¶
Default: %Y-%m-%d %H:%M:%S
Description: A valid Python strftime string for a datetime.
Note
If for some reason you want to change the way either the date or the datetime string is formatted, you can override those formats using valid Python datetime.strftime()
format codes.
If you need a refresher on these codes, have a look at the Python documentation found here: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior.
jekyll_debug
¶
Default: false
Description: If set to true
, the application will print Jekyll debug information to the Sublime Text console and can be retrieved by usingCtrl + `
.
jekyll_utility_disable
¶
Default: false
Description: If set to true
, the application will hide the Jekyll Utility commands from the Command Palatte, and disable the commands from the menu.
Project Settings¶
For per-project settings, make sure you add your Jekyll settings correctly to your Project settings file. You can typically edit your Project file under Project > Edit Project.
Warning
These should be absolute paths, not relative paths!
Also, the paths should follow your system-specific path convention. For example, Windows machines should have a path similar to C:\\Users\\username\\site\\_posts
. Unix/Linux systems should have a path similar to /Users/username/site/_posts
.
# some-file.sublime-settings
{
"folders":
[
{
"follow_symlinks": true,
"path": "/Users/username/site/"
}
],
"settings":
{
"Jekyll":
{
"jekyll_posts_path": "/Users/username/site/_posts",
"jekyll_drafts_path": "/Users/username/site/_drafts",
"jekyll_uploads_path": "/Users/username/site/uploads",
"jekyll_templates_path": "/Users/username/site/_templates",
}
}
}
See also
Read the conversation on issue #16 if you have questions on formatting your Project settings file correctly.
Commands¶
sublime-jekyll ships with a number of commands for helping you get things done more efficiently.
Warning
Users who are upgrading from pre-v3.0 will want to review the Jekyll Utility commands. These allow you to easily migrate over your sublime-settings
so that you can continue using sublime-jekyll moving forward.
If you prefer to hide these commands and remove them from the Command Palatte, you can set the settings key jekyll_utility_disable
to true
and restart Sublime Text.
Jekyll¶
New post¶
Command: jekyll_new_post
Description: Brings up an input panel for naming and creating a new post in your _posts
directory. The post title is automatically slugified, and the current date is appended to the title.
New post from template¶
Command: jekyll_new_post_from_template
Description: Brings up a quick panel for selecting a post template. Once selected, brings up an input panel for naming and creating a new post in your _posts
directory. The post title is automatically slugified, and the current date is appended to the title.
Remove post¶
Command: jekyll_remove_post
Description: Brings up a quick panel for choosing a post in your _posts
directory to delete. This action is irreversible.
Open post…¶
Command: jekyll_open_post
Description: Brings up a quick panel for choosing an existing post in your _posts
directory.
New draft¶
Command: jekyll_new_draft
Description: Brings up an input panel for naming and creating a new draft in your _drafts
directory. The post title is automatically slugified, however no date is appended to the title.
New draft from template¶
Command: jekyll_new_draft_from_template
Description: Brings up a quick panel for selecting a post template. Once selected, brings up an input panel for naming and creating a new post in your _drafts
directory. The post title is automatically slugified.
Promote draft to post¶
Command: jekyll_promote_draft
Description: Brings up a quick panel for choosing an existing draft in your _drafts
directory to move to the_posts
directory. The post title is automatically updated with the current date.
Remove draft¶
Command: jekyll_remove_draft
Description: Brings up a quick panel for choosing a post in your _drafts
directory to delete. This action is irreversible.
Open draft¶
Command: jekyll_open_draft
Description: Brings up a quick panel for choosing an existing draft in your _drafts
directory.
New template¶
Command: jekyll_new_template
Description: Brings up an input panel for naming and creating a new post template in your Jekyll Templates
directory.
Edit template¶
Command: jekyll_edit_template
Description: Brings up a quick panel for choosing an existing template in your Jekyll Templates
directory.
Remove template¶
Command: jekyll_remove_template
Description: Brings up a quick panel for choosing an existing template in your Jekyll Templates
directory to delete. This action is irreversible.
Browse templates…¶
Command: jekyll_browse_templates
Description: Opens your Jekyll Templates
directory in your system-specific default file browser (helpful for managing templates directly).
Edit _config.yml¶
Command: jekyll_edit_config
Description: Opens your _config.yml
file if it is found in yourjekyll_posts_path
parent directory. Helpful for making quick changes to Jekyll blog settings.
Insert current date¶
Command: jekyll_insert_date
Args: {"format": "date"}
Description: Inserts the current date at the cursor using the format specified by the jekyll_date_format
setting.
Insert current datetime¶
Command: jekyll_insert_datetime
Args: {"format": "datetime"}
Description: Inserts the current datetime at the cursor using the format specified by the jekyll_datetime_format
setting.
Insert upload¶
Command: jekyll_insert_upload
Description: Brings up a quick panel for choosing an existing file in your uploads
directory, and adds a pre-formatted link at the cursor.
Jekyll Utility¶
Migrate user settings¶
Command: jekyll_migrate_user_settings
Description: Attempts to migrate pre-v3.0 User Settings files to the new v3.0 format. This command only needs to be run once per machine/user. Settings backup files can be found in the Jekyll Backup
folder within yourUser
directory.
Migrate project settings¶
Command: jekyll_migrate_project_settings
Description: Attempts to migrate pre-v3.0 Project Settings files to the new v3.0 format. This command should be run for each Project using sublime-jekyll settings keys. Settings backup files can be found in the Jekyll Backup
folder within yourUser
directory.
Note
Users of Sublime Text 2 will not see the Migrate project settings
command, as there is no project API. You will need to update your project settings manually.
Browse backups…¶
Command: jekyll_browse_backups
Description: Opens your Jekyll Backups
directory in your system-specific default file browser (helpful for managing backups directly).
Snippets¶
sublime-jekyll ships with a number of handy Liquid template snippets so you don’t waste time remembering code or looking up documentation.
Common¶
Assign¶
Trigger: assign
Description: Create a Liquid template variable.
Content: {% assign $1 = $2 %}
Break¶
Trigger: break
Description: Insert a Liquid template break tag.
Content: {% break %}
Capture¶
Trigger: capture
Description: Capture a string and assign to a variable.
Content: {% capture $1 %} $0 {% endcapture %}
Case¶
Trigger: case
Description: Creates the start of a switch statement (used with
{% when %}
tags).Content: {% case $1 %} $0 {% endcase %}
Comment¶
Trigger: comment
Description: Add a comment block.
Content: {% comment $1 %} $0 {% endcomment %}
Context variable¶
Trigger: va
Description: Create a variable.
Content: {{ $1 }}
Continue¶
Trigger: continue
Description: Add a continue tag to a loop.
Content: {% continue %}
Cycle¶
Trigger: cycle
Description: Cycle through values in a for block.
Content: {% cycle $1 %}
Decrement¶
Trigger: decrement
Description: Decrement an amount.
Content: {% decrement $1 %}
Else/if¶
Trigger: elsif
Description: Add an else/if clause.
Content: {% elsif $1 %}
For¶
Trigger: for
Description: Create a for block.
Content: {% for $1 in $2 %} $0 {% endfor %}
If¶
Trigger: if
Description: Create an if statement.
Content: {% if $1 %} $0 {% endif %}
If/else¶
Trigger: ifelse
Description: Create an if/else statement.
Content: {% if $1 %} $2 {% else %} $0 {% endif %}
Increment¶
Trigger: increment
Description: Increment an amount.
Content: {% increment $1 %}
Raw¶
Trigger: raw
Description: Create a raw/unprocessed block.
Content: {% raw %} $0 {% endraw %}
Unless¶
Trigger: unless
Description: Opposite of an if clause.
Content: {% unless $1 %} $0 {% endunless %}
When¶
Trigger: when
Description: Part of a switch statement.
Content: {% when $1 %}
Obscure¶
Gist¶
Trigger: gist
Description: Quickly include a tag for a Gist code snippet.
Content: {% gist $1 %}
Highlight¶
Trigger: highlight
Description: Quickly include a code block for use with the Rouge syntax highlighter.
Content: {% highlight $1 %} $0 {% endhighlight %}
Include¶
Trigger: include
Description: Include a named template.
Content: {% include $1 %}
Include relative¶
Trigger: include_relative
Description: Include a named template relative to the current file.
Content: {% include_relative $1 %}
Post URL¶
Trigger: post_url
Description: Quickly include a tag for the current post’s permalink URL.
Content: {% post_url $1 %}
Completions¶
sublime-jekyll ships with a large number of auto-completions for helping you get things done more efficiently. Included are a number of standard Liquid template filters, as well as Jekyll specific filters and template variables.
Note
If wanted, you can update your Markdown.sublime-settings
file to include some overrides to trigger completions in Markdown files. Add "auto_complete_selector": "text.html.markdown"
and "auto_complete_triggers": [ {"selector": "text.html.markdown"} ]
as new key:value pairs.
Global Variables¶
Trigger | Contents |
---|---|
site | site |
page | page |
layout | layout |
content | content |
paginator | paginator |
Site Variables¶
Trigger | Contents |
---|---|
site.time | site.time |
site.pages | site.pages |
site.posts | site.posts |
site.related_posts | site.related_posts |
site.static_files | site.static_files |
site.html_pages | site.html_pages |
site.html_files | site.html_files |
site.collections | site.collections |
site.data | site.data.$1 |
site.documents | site.documents.$1 |
site.categories | site.categories.$1 |
site.tags | site.tags.$1 |
Page Variables¶
Trigger | Contents |
---|---|
page.content | page.content |
page.title | page.content |
page.excerpt | page.excerpt |
page.url | page.url |
page.date | page.date |
page.id | page.id |
page.categories | page.categories |
page.tags | page.tags |
page.path | page.path |
page.next | page.next |
page.previous | page.previous |
Paginator Variables¶
Trigger | Contents |
---|---|
paginator.per_page | paginator.per_page |
paginator.posts | paginator.posts |
paginator.total_posts | paginator.total_posts |
paginator.total_pages | paginator.total_pages |
paginator.page | paginator.page |
paginator.previous_page | paginator.previous_page |
paginator.previous_page_path | paginator.previous_page_path |
paginator.next_page | paginator.next_page |
paginator.next_page_path | paginator.next_page_path |
Forloop Variables¶
Trigger | Contents |
---|---|
forloop.first | forloop.first |
forloop.index | forloop.index |
forloop.index0 | forloop.index0 |
forloop.last | forloop.last |
forloop.length | forloop.length |
forloop.rindex | forloop.rindex |
forloop.rindex0 | forloop.rindex0 |
Array Filters¶
Trigger | Contents |
---|---|
join | join |
first | first |
last | last |
concat | concat |
index | index |
map | map |
reverse | reverse |
size | size |
sort | sort |
uniq | uniq |
String Filters¶
Trigger | Contents |
---|---|
append | append:'$1' |
capitalize | capitalize |
downcase | downcase |
escape | escape |
newline_to_br | newline_to_br |
pluralize | pluralize |
prepend | prepend:'$1' |
remove | remove:'$1' |
remove_first | remove_first:'$1' |
replace | replace:'$1' |
replace_first | replace_first:'$1' |
slice | slice:$2, $1 |
split | split:'$1' |
strip | strip |
lstrip | lstrip |
rstrip | rstrip |
strip_html | strip_html |
strip_newlines | strip_newlines |
truncate | truncate:$2, '$1' |
truncatewords | truncatewords |
upcase | upcase |
Math Filters¶
Trigger | Contents |
---|---|
abs | abs:$1 |
ceil | ceil:$1 |
divided_by | divided_by:$1 |
floor | floor |
minus | minus:$1 |
plus | plus:$1 |
round | round |
times | times:$1 |
modulo | modulo:$1 |
Handy Filters¶
Trigger | Contents |
---|---|
relative_url | relative_url |
absolute_url | absolute_url |
date_to_xmlschema | date_to_xmlschema |
date_to_rfc822 | date_to_rfc822 |
date_to_string | date_to_string |
date_to_long_string | date_to_long_string |
where | where:'$2','$1' |
where_exp | where_exp:'$2','$1' |
group_by | group_by:'$1' |
group_by_exp | group_by_exp:'$1' |
xml_escape | xml_escape |
cgi_escape | cgi_escape |
uri_escape | uri_escape |
number_of_words | number_of_words |
array_to_sentence_string | array_to_sentence_string |
markdownify | markdownify |
smartify | smartify |
scssify | scssify |
sassisfy | sassisfy |
slugify | slugify |
jsonify | jsonify |
normalize_whitespace | normalize_whitespace |
sample | sample |
to_integer | to_integer |
push | push |
pop | pop |
shift | shift |
unshift | unshift |
inspect | inspect |
date | date |
Templates¶
sublime-jekyll allows new drafts and posts to be created from user-defined YAML front-matter templates. This allows for a truly customized approach to writing posts.
Templates are stored by default in the User/Jekyll Templates
directory. You can change this by providing your own directory path in the jekyll_templates_path
settings key.
Note
If you plan on using the jekyll_auto_find_paths
settings key, make sure you name your templates directory _templates
. This is what the plug-in will be looking for to locate a directory.
The basic format of a post template should just include the front-matter.
---
layout: post
category: blog
---
Post templates support Sublime Text snippet formatting for more complex layouts and increased automation in your writing. For more documentation on using snippet variables, have a look at the official Sublime Text snippet documentation.
---
layout: ${1:post}
tags: [$2]
image:
url:
alt:
---
Although the post title
key will be added automatically as the first key in the template, you can optionally pass a blank title:
key anywhere in the front-matter and it will be replaced with the title of your post.
---
layout: post
title:
category: blog
---
When creating a new template, you will be able to optionally pass in a description of what that template is used for. This is helpful if you have multiple templates and you want to remember what each is used for. The description will show in the quick panel under the name of the template. The description is stored as a YAML comment on the first line of the file, and will be stripped out when a new draft or post is created.
# Used this for image posts
---
layout: ${1:image}
tags: ['$2']
image:
url: $3
alt: $4
---
Note
sublime-jekyll does not provide YAML front-matter validation or. If you need help with YAML formatting, please refer to the official Jekyll documentation.
Build System¶
If desired, you can add a custom Jekyll build system to your Sublime projects. This allows you to create a specific build system for each Jekyll project you’re working on.
From what I can tell, a project-specific build system needs to be used, as opposed to a standard build system. This is because the jekyll
CLT command must be run from the main Jekyll folder that contains the _config.yml file (which cannot be guaranteed to be the current project folder).
{
"folders":
[
{
"follow_symlinks": true,
"path": "/Users/username/site/"
}
],
"build_systems":
[
// This will build your Jekyll site, and print a trace to the console
{
"name": "Jekyll",
// Change this directory to match your top-level Jekyll project folder
"working_dir": "$project_path",
"cmd": "jekyll build -t",
"shell": true,
"encoding": "UTF-8"
}
]
}
Note
You can read up further on Build systems in general from the documentation found here:
http://sublimetext.info/docs/en/reference/build_systems.html http://docs.sublimetext.info/en/latest/reference/build_systems.html
License & Credits¶
sublime-jekyll is licensed under the MIT license.
Authors¶
Contributors¶
This package gets better with more feedback and contributions from you! If you want to participate in the community development of this open source project, be sure to read the contributing guide before you begin.
A huge thanks already to our current contributors.
FAQs¶
I’m getting Unable to find path information errors.¶
In order for sublime-jekyll to create new posts for your static site, it must know where to put them. There are 2 required settings that must be set before you use this package: jekyll_posts_path
and jekyll_drafts_path
. If those are not set in either your User settings file, or your Project settings file, sublime-jekyll will fail with a MissingPathException
.
What happened to all the syntax files?¶
Syntax files in Sublime Text suck - period. They were becoming really difficult to manage and debug, and in my opinion they weren’t all that good anyway. I have moved them to a separate repository where folks can feel free to push pull requests for any bugs or fixes. I don’t plan on maintaining this respository with proactive updates (outside of community pull requests).
If you want my recommendation for a syntax package, install Markdown Extended or MarkdownEditing - both are very good and well maintained.
Where do I put my Project settings?¶
When you create a new project in Sublime Text, you are asked to save a file with a suffix of .sublime-project. By default, that file has some minimal settings, and allows you to control things about your specific project (project documentation). To add Project specific settings for sublime-jekyll, you can just add your Jekyll settings under the “settings” key in your .sublime-project file.
{
"folders":
[
{
"follow_symlinks": true,
"path": "/Users/username/site/"
}
],
"settings":
{
"Jekyll":
{
"jekyll_posts_path": "/Users/username/site/_posts",
"jekyll_drafts_path": "/Users/username/site/_drafts",
}
}
}
How do I log a bug?¶
Bugs suck - and I’m sorry you had to find one. I’m typically pretty responsive to fixing them if you help me gather as much information as possible.
First, enable debug mode for sublime-jekyll by setting the
jekyll_debug
setting totrue
, and restart Sublime Text.Next, try to reproduce the bug again. If it still happens, open up the Sublime console (
Ctrl + `
or View > Show Console) and copy the Jekyll-specific debugging output (it should have aJekyll
orJekyll Utility
prefix).Check the list of open issues on the GitHub issue tracker for similar problems with other users. If you find one, add your name to it.
If no issues exist, open a new one being sure to include the following information:
- A summary or description of the specific issue
- Your version of Sublime Text (2 or 3, as well as build)
- Your operating system (Windows, OS X, Linux)
- The debug output of the Sublime console
Lastly, be open to us asking some questions about your bug as we attempt to reproduce and squash it!