Class: Jekyll::URL

Inherits:
Object
  • Object
show all
Defined in:
lib/jekyll/url.rb

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ URL

options - One of :permalink or :template must be supplied.

:template     - The String used as template for URL generation,
                for example "/:path/:basename:output_ext", where
                a placeholder is prefixed with a colon.
:placeholders - A hash containing the placeholders which will be
                replaced when used inside the template. E.g.
                { "year" => Time.now.strftime("%Y") } would replace
                the placeholder ":year" with the current year.
:permalink    - If supplied, no URL will be generated from the
                template. Instead, the given permalink will be
                used as URL.

26
27
28
29
30
31
32
33
34
# File 'lib/jekyll/url.rb', line 26

def initialize(options)
  @template     = options[:template]
  @placeholders = options[:placeholders] || {}
  @permalink    = options[:permalink]

  if (@template || @permalink).nil?
    raise ArgumentError, "One of :template or :permalink must be supplied."
  end
end

Class Method Details

.escape_path(path) ⇒ Object

Escapes a path to be a valid URL path segment

path - The path to be escaped.

Examples:

URL.escape_path("/a b")
# => "/a%20b"

Returns the escaped path.


99
100
101
102
103
104
105
106
107
108
109
110
111
# File 'lib/jekyll/url.rb', line 99

def self.escape_path(path)
  # Because URI.escape doesn't escape '?', '[' and ']' by default,
  # specify unsafe string (except unreserved, sub-delims, ":", "@" and "/").
  #
  # URI path segment is defined in RFC 3986 as follows:
  #   segment       = *pchar
  #   pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"
  #   unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
  #   pct-encoded   = "%" HEXDIG HEXDIG
  #   sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
  #                 / "*" / "+" / "," / ";" / "="
  URI.escape(path, /[^a-zA-Z\d\-._~!$&'()*+,;=:@\/]/).encode('utf-8')
end

.unescape_path(path) ⇒ Object

Unescapes a URL path segment

path - The path to be unescaped.

Examples:

URL.unescape_path("/a%20b")
# => "/a b"

Returns the unescaped path.


123
124
125
# File 'lib/jekyll/url.rb', line 123

def self.unescape_path(path)
  URI.unescape(path.encode('utf-8'))
end

Instance Method Details

#generate_url(template) ⇒ Object

Internal: Generate the URL by replacing all placeholders with their respective values in the given template

Returns the unsanitized String URL


61
62
63
64
65
66
67
68
69
70
71
# File 'lib/jekyll/url.rb', line 61

def generate_url(template)
  @placeholders.inject(template) do |result, token|
    break result if result.index(':').nil?
    if token.last.nil?
      # Remove leading '/' to avoid generating urls with `//`
      result.gsub(/\/:#{token.first}/, '')
    else
      result.gsub(/:#{token.first}/, self.class.escape_path(token.last))
    end
  end
end

Generates a URL from the permalink

Returns the _unsanitized String URL


46
47
48
# File 'lib/jekyll/url.rb', line 46

def generated_permalink
  (@generated_permalink ||= generate_url(@permalink)) if @permalink
end

#generated_urlObject

Generates a URL from the template

Returns the unsanitized String URL


53
54
55
# File 'lib/jekyll/url.rb', line 53

def generated_url
  @generated_url ||= generate_url(@template)
end

#sanitize_url(in_url) ⇒ Object

Returns a sanitized String URL


74
75
76
77
78
79
80
81
82
83
84
85
86
87
# File 'lib/jekyll/url.rb', line 74

def sanitize_url(in_url)
  url = in_url \
    # Remove all double slashes
    .gsub(/\/\//, '/') \
    # Remove every URL segment that consists solely of dots
    .split('/').reject{ |part| part =~ /^\.+$/ }.join('/') \
    # Always add a leading slash
    .gsub(/\A([^\/])/, '/\1')

  # Append a trailing slash to the URL if the unsanitized URL had one
  url << "/" if in_url.end_with?("/")

  url
end

#to_sObject

The generated relative URL of the resource

Returns the String URL


39
40
41
# File 'lib/jekyll/url.rb', line 39

def to_s
  sanitize_url(generated_permalink || generated_url)
end