sublime-jekyll

https://img.shields.io/github/license/23maverick23/sublime-jekyll.svg https://img.shields.io/github/tag/23maverick23/sublime-jekyll.svg https://img.shields.io/packagecontrol/dt/Jekyll.svg https://img.shields.io/maintenance/yes/2017.svg

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) or Command + 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 of true or false.
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 called image.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, or Plain 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 using Ctrl + `.
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 your jekyll_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 your User 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 your User 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.

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.

Storyboard

Keep track of our stories on waffle.io, or visit our issue tracker on GitHub.

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 to true, 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 a Jekyll or Jekyll 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:

    1. A summary or description of the specific issue
    2. Your version of Sublime Text (2 or 3, as well as build)
    3. Your operating system (Windows, OS X, Linux)
    4. 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!