Class: Jekyll::Document
- Inherits:
-
Object
- Object
- Jekyll::Document
- Extended by:
- Forwardable
- Includes:
- Comparable
- Defined in:
- lib/jekyll/document.rb
Constant Summary collapse
- YAML_FRONT_MATTER_REGEXP =
%r!\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)!m
- DATELESS_FILENAME_MATCHER =
%r!^(?:.+/)*(.*)(\.[^.]+)$!
- DATE_FILENAME_MATCHER =
%r!^(?:.+/)*(\d{2,4}-\d{1,2}-\d{1,2})-(.*)(\.[^.]+)$!
Instance Attribute Summary collapse
-
#collection ⇒ Object
readonly
Returns the value of attribute collection.
-
#content ⇒ Object
Returns the value of attribute content.
-
#extname ⇒ Object
readonly
Returns the value of attribute extname.
-
#output ⇒ Object
Returns the value of attribute output.
-
#path ⇒ Object
readonly
Returns the value of attribute path.
-
#site ⇒ Object
readonly
Returns the value of attribute site.
Instance Method Summary collapse
-
#<=>(other) ⇒ Object
Compare this document against another document.
- #[](key) ⇒ Object
-
#asset_file? ⇒ Boolean
Determine whether the document is an asset file.
-
#basename ⇒ Object
The base filename of the document.
-
#basename_without_ext ⇒ Object
The base filename of the document, without the file extname.
-
#categories_from_path(special_dir) ⇒ Object
Add superdirectories of the special_dir to categories.
-
#cleaned_relative_path ⇒ Object
Produces a “cleaned” relative path.
-
#coffeescript_file? ⇒ Boolean
Determine whether the document is a CoffeeScript file.
-
#data ⇒ Object
Fetch the Document’s data.
- #date ⇒ Object
-
#destination(base_directory) ⇒ Object
The full path to the output file.
-
#draft? ⇒ Boolean
Returns whether the document is a draft.
-
#excerpt_separator ⇒ Object
The Document excerpt_separator, from the YAML Front-Matter or site default excerpt_separator value.
-
#generate_excerpt? ⇒ Boolean
Whether to generate an excerpt.
- #id ⇒ Object
-
#initialize(path, relations = {}) ⇒ Document
constructor
Create a new Document.
-
#inspect ⇒ Object
The inspect string for this document.
-
#merge_data!(other, source: "YAML front matter") ⇒ Object
Merge some data in with this document’s data.
-
#method_missing(method, *args, &blck) ⇒ Object
Override of method_missing to check in @data for the key.
- #next_doc ⇒ Object
-
#no_layout? ⇒ Boolean
Determine whether the file should be rendered with a layout.
-
#output_ext ⇒ Object
The output extension of the document.
-
#permalink ⇒ Object
The permalink for this Document.
-
#place_in_layout? ⇒ Boolean
Determine whether the file should be placed into layouts.
- #populate_categories ⇒ Object
- #populate_tags ⇒ Object
- #previous_doc ⇒ Object
-
#published? ⇒ Boolean
Whether the file is published or not, as indicated in YAML front-matter.
-
#read(opts = {}) ⇒ Object
Read in the file and assign the content and data based on the file contents.
-
#related_posts ⇒ Object
Calculate related posts.
-
#relative_path ⇒ Object
The path to the document, relative to the collections_dir.
-
#render_with_liquid? ⇒ Boolean
Determine whether the file should be rendered with Liquid.
-
#respond_to?(method, include_private = false) ⇒ Boolean
Override of normal respond_to? to match method_missing’s logic for looking in @data.
- #respond_to_missing?(method) ⇒ Boolean
-
#sass_file? ⇒ Boolean
Determine whether the document is a Sass file.
- #source_file_mtime ⇒ Object
-
#to_liquid ⇒ Object
Create a Liquid-understandable version of this Document.
-
#to_s ⇒ Object
The string representation for this document.
- #trigger_hooks(hook_name, *args) ⇒ Object
-
#url ⇒ Object
The computed URL for the document.
-
#url_placeholders ⇒ Object
Construct a Hash of key-value pairs which contain a mapping between a key in the URL template and the corresponding value for this document.
-
#url_template ⇒ Object
The URL template where the document would be accessible.
-
#write(dest) ⇒ Object
Write the generated Document file to the destination directory.
-
#write? ⇒ Boolean
Determine whether this document should be written.
-
#yaml_file? ⇒ Boolean
Determine whether the document is a YAML file.
Constructor Details
#initialize(path, relations = {}) ⇒ Document
Create a new Document.
path - the path to the file relations - a hash with keys :site and :collection, the values of which
are the Jekyll::Site and Jekyll::Collection to which this
Document belong.
Returns nothing.
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
# File 'lib/jekyll/document.rb', line 25 def initialize(path, relations = {}) @site = relations[:site] @path = path @extname = File.extname(path) @collection = relations[:collection] @has_yaml_header = nil if draft? categories_from_path("_drafts") else categories_from_path(collection.relative_directory) end data.default_proc = proc do |_, key| site.frontmatter_defaults.find(relative_path, collection.label, key) end trigger_hooks(:post_init) end |
Dynamic Method Handling
This class handles dynamic methods through the method_missing method
#method_missing(method, *args, &blck) ⇒ Object
Override of method_missing to check in @data for the key.
373 374 375 376 377 378 379 380 381 382 |
# File 'lib/jekyll/document.rb', line 373 def method_missing(method, *args, &blck) if data.key?(method.to_s) Jekyll::Deprecator. "Document##{method} is now a key "\ "in the #data hash." Jekyll::Deprecator. "Called by #{caller(0..0)}." data[method.to_s] else super end end |
Instance Attribute Details
#collection ⇒ Object (readonly)
Returns the value of attribute collection.
8 9 10 |
# File 'lib/jekyll/document.rb', line 8 def collection @collection end |
#content ⇒ Object
Returns the value of attribute content.
9 10 11 |
# File 'lib/jekyll/document.rb', line 9 def content @content end |
#extname ⇒ Object (readonly)
Returns the value of attribute extname.
8 9 10 |
# File 'lib/jekyll/document.rb', line 8 def extname @extname end |
#output ⇒ Object
Returns the value of attribute output.
9 10 11 |
# File 'lib/jekyll/document.rb', line 9 def output @output end |
#path ⇒ Object (readonly)
Returns the value of attribute path.
8 9 10 |
# File 'lib/jekyll/document.rb', line 8 def path @path end |
#site ⇒ Object (readonly)
Returns the value of attribute site.
8 9 10 |
# File 'lib/jekyll/document.rb', line 8 def site @site end |
Instance Method Details
#<=>(other) ⇒ Object
Compare this document against another document. Comparison is a comparison between the 2 paths of the documents.
Returns -1, 0, +1 or nil depending on whether this doc’s path is less than,
equal or greater than the other doc's path. See String#<=> for more details.
304 305 306 307 308 309 |
# File 'lib/jekyll/document.rb', line 304 def <=>(other) return nil unless other.respond_to?(:data) cmp = data["date"] <=> other.data["date"] cmp = path <=> other.path if cmp.nil? || cmp.zero? cmp end |
#[](key) ⇒ Object
214 215 216 |
# File 'lib/jekyll/document.rb', line 214 def [](key) data[key] end |
#asset_file? ⇒ Boolean
Determine whether the document is an asset file. Asset files include CoffeeScript files and Sass/SCSS files.
Returns true if the extname belongs to the set of extensions
that asset files use.
138 139 140 |
# File 'lib/jekyll/document.rb', line 138 def asset_file? sass_file? || coffeescript_file? end |
#basename ⇒ Object
The base filename of the document.
Returns the base filename of the document.
106 107 108 |
# File 'lib/jekyll/document.rb', line 106 def basename @basename ||= File.basename(path) end |
#basename_without_ext ⇒ Object
The base filename of the document, without the file extname.
Returns the basename without the file extname.
99 100 101 |
# File 'lib/jekyll/document.rb', line 99 def basename_without_ext @basename_without_ext ||= File.basename(path, ".*") end |
#categories_from_path(special_dir) ⇒ Object
Add superdirectories of the special_dir to categories. In the case of es/_posts, ‘es’ is added as a category. In the case of _posts/es, ‘es’ is NOT added as a category.
Returns nothing.
393 394 395 396 397 398 399 400 |
# File 'lib/jekyll/document.rb', line 393 def categories_from_path(special_dir) superdirs = relative_path.sub(%r!#{special_dir}(.*)!, "") .split(File::SEPARATOR) .reject do |c| c.empty? || c == special_dir || c == basename end merge_data!({ "categories" => superdirs }, :source => "file path") end |
#cleaned_relative_path ⇒ Object
Produces a “cleaned” relative path. The “cleaned” relative path is the relative path without the extname
and with the collection's directory removed as well.
This method is useful when building the URL of the document.
Examples:
When relative_path is "_methods/site/generate.md":
cleaned_relative_path
# => "/site/generate"
Returns the cleaned relative path of the document.
121 122 123 124 |
# File 'lib/jekyll/document.rb', line 121 def cleaned_relative_path @cleaned_relative_path ||= relative_path[0..-extname.length - 1].sub(collection.relative_directory, "") end |
#coffeescript_file? ⇒ Boolean
Determine whether the document is a CoffeeScript file.
Returns true if extname == .coffee, false otherwise.
152 153 154 |
# File 'lib/jekyll/document.rb', line 152 def coffeescript_file? extname == ".coffee" end |
#data ⇒ Object
Fetch the Document’s data.
Returns a Hash containing the data. An empty hash is returned if
no data was read.
49 50 51 |
# File 'lib/jekyll/document.rb', line 49 def data @data ||= {} end |
#date ⇒ Object
63 64 65 |
# File 'lib/jekyll/document.rb', line 63 def date data["date"] ||= (draft? ? source_file_mtime : site.time) end |
#destination(base_directory) ⇒ Object
The full path to the output file.
base_directory - the base path of the output directory
Returns the full path to the output file of this document.
223 224 225 226 227 228 229 230 231 232 |
# File 'lib/jekyll/document.rb', line 223 def destination(base_directory) dest = site.in_dest_dir(base_directory) path = site.in_dest_dir(dest, URL.unescape_path(url)) if url.end_with? "/" path = File.join(path, "index.html") else path << output_ext unless path.end_with? output_ext end path end |
#draft? ⇒ Boolean
Returns whether the document is a draft. This is only the case if the document is in the ‘posts’ collection but in a different directory than ‘_posts’.
Returns whether the document is a draft.
76 77 78 79 |
# File 'lib/jekyll/document.rb', line 76 def draft? data["draft"] ||= relative_path.index(collection.relative_directory).nil? && collection.label == "posts" end |
#excerpt_separator ⇒ Object
The Document excerpt_separator, from the YAML Front-Matter or site default excerpt_separator value
Returns the document excerpt_separator
325 326 327 |
# File 'lib/jekyll/document.rb', line 325 def excerpt_separator (data["excerpt_separator"] || site.config["excerpt_separator"]).to_s end |
#generate_excerpt? ⇒ Boolean
Whether to generate an excerpt
Returns true if the excerpt separator is configured.
332 333 334 |
# File 'lib/jekyll/document.rb', line 332 def generate_excerpt? !excerpt_separator.empty? end |
#id ⇒ Object
355 356 357 |
# File 'lib/jekyll/document.rb', line 355 def id @id ||= File.join(File.dirname(url), (data["slug"] || basename_without_ext).to_s) end |
#inspect ⇒ Object
The inspect string for this document. Includes the relative path and the collection label.
Returns the inspect string for this document.
288 289 290 |
# File 'lib/jekyll/document.rb', line 288 def inspect "#<Jekyll::Document #{relative_path} collection=#{collection.label}>" end |
#merge_data!(other, source: "YAML front matter") ⇒ Object
Merge some data in with this document’s data.
Returns the merged data.
56 57 58 59 60 61 |
# File 'lib/jekyll/document.rb', line 56 def merge_data!(other, source: "YAML front matter") merge_categories!(other) Utils.deep_merge_hashes!(data, other) merge_date!(source) data end |
#next_doc ⇒ Object
336 337 338 339 340 341 |
# File 'lib/jekyll/document.rb', line 336 def next_doc pos = collection.docs.index { |post| post.equal?(self) } if pos && pos < collection.docs.length - 1 collection.docs[pos + 1] end end |
#no_layout? ⇒ Boolean
Determine whether the file should be rendered with a layout.
Returns true if the Front Matter specifies that ‘layout` is set to `none`.
168 169 170 |
# File 'lib/jekyll/document.rb', line 168 def no_layout? data["layout"] == "none" end |
#output_ext ⇒ Object
The output extension of the document.
Returns the output extension
92 93 94 |
# File 'lib/jekyll/document.rb', line 92 def output_ext @output_ext ||= Jekyll::Renderer.new(site, self).output_ext end |
#permalink ⇒ Object
The permalink for this Document. Permalink is set via the data Hash.
Returns the permalink or nil if no permalink was set in the data.
199 200 201 |
# File 'lib/jekyll/document.rb', line 199 def permalink data && data.is_a?(Hash) && data["permalink"] end |
#place_in_layout? ⇒ Boolean
Determine whether the file should be placed into layouts.
Returns false if the document is set to ‘layouts: none`, or is either an
asset file or a yaml file. Returns true otherwise.
176 177 178 |
# File 'lib/jekyll/document.rb', line 176 def place_in_layout? !(asset_file? || yaml_file? || no_layout?) end |
#populate_categories ⇒ Object
402 403 404 405 406 407 408 409 410 |
# File 'lib/jekyll/document.rb', line 402 def populate_categories merge_data!({ "categories" => ( Array(data["categories"]) + Utils.pluralized_array_from_hash( data, "category", "categories" ) ).map(&:to_s).flatten.uniq, }) end |
#populate_tags ⇒ Object
412 413 414 415 416 |
# File 'lib/jekyll/document.rb', line 412 def merge_data!({ "tags" => Utils.pluralized_array_from_hash(data, "tag", "tags").flatten, }) end |
#previous_doc ⇒ Object
343 344 345 346 347 348 |
# File 'lib/jekyll/document.rb', line 343 def previous_doc pos = collection.docs.index { |post| post.equal?(self) } if pos && pos > 0 collection.docs[pos - 1] end end |
#published? ⇒ Boolean
Whether the file is published or not, as indicated in YAML front-matter
Returns ‘false’ if the ‘published’ key is specified in the YAML front-matter and is ‘false’. Otherwise returns ‘true’.
252 253 254 |
# File 'lib/jekyll/document.rb', line 252 def published? !(data.key?("published") && data["published"] == false) end |
#read(opts = {}) ⇒ Object
Read in the file and assign the content and data based on the file contents. Merge the frontmatter of the file with the frontmatter default values
Returns nothing.
261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 |
# File 'lib/jekyll/document.rb', line 261 def read(opts = {}) Jekyll.logger.debug "Reading:", relative_path if yaml_file? @data = SafeYAML.load_file(path) else begin merge_defaults read_content(**opts) read_post_data rescue StandardError => e handle_read_error(e) end end end |
#related_posts ⇒ Object
Calculate related posts.
Returns an Array of related Posts.
362 363 364 |
# File 'lib/jekyll/document.rb', line 362 def @related_posts ||= Jekyll::RelatedPosts.new(self).build end |
#relative_path ⇒ Object
The path to the document, relative to the collections_dir.
Returns a String path which represents the relative path from the collections_dir to this document.
85 86 87 |
# File 'lib/jekyll/document.rb', line 85 def relative_path @relative_path ||= path.sub("#{site.collections_path}/", "") end |
#render_with_liquid? ⇒ Boolean
Determine whether the file should be rendered with Liquid.
Returns false if the document is either an asset file or a yaml file,
or if the document doesn't contain any Liquid Tags or Variables,
true otherwise.
161 162 163 |
# File 'lib/jekyll/document.rb', line 161 def render_with_liquid? !(coffeescript_file? || yaml_file? || !Utils.has_liquid_construct?(content)) end |
#respond_to?(method, include_private = false) ⇒ Boolean
Override of normal respond_to? to match method_missing’s logic for looking in @data.
368 369 370 |
# File 'lib/jekyll/document.rb', line 368 def respond_to?(method, include_private = false) data.key?(method.to_s) || super end |
#respond_to_missing?(method) ⇒ Boolean
384 385 386 |
# File 'lib/jekyll/document.rb', line 384 def respond_to_missing?(method, *) data.key?(method.to_s) || super end |
#sass_file? ⇒ Boolean
Determine whether the document is a Sass file.
Returns true if extname == .sass or .scss, false otherwise.
145 146 147 |
# File 'lib/jekyll/document.rb', line 145 def sass_file? %w(.sass .scss).include?(extname) end |
#source_file_mtime ⇒ Object
67 68 69 |
# File 'lib/jekyll/document.rb', line 67 def source_file_mtime @source_file_mtime ||= File.mtime(path) end |
#to_liquid ⇒ Object
Create a Liquid-understandable version of this Document.
Returns a Hash representing this Document’s data.
280 281 282 |
# File 'lib/jekyll/document.rb', line 280 def to_liquid @to_liquid ||= Drops::DocumentDrop.new(self) end |
#to_s ⇒ Object
The string representation for this document.
Returns the content of the document
295 296 297 |
# File 'lib/jekyll/document.rb', line 295 def to_s output || content || "NO CONTENT" end |
#trigger_hooks(hook_name, *args) ⇒ Object
350 351 352 353 |
# File 'lib/jekyll/document.rb', line 350 def trigger_hooks(hook_name, *args) Jekyll::Hooks.trigger collection.label.to_sym, hook_name, self, *args if collection Jekyll::Hooks.trigger :documents, hook_name, self, *args end |
#url ⇒ Object
The computed URL for the document. See ‘Jekyll::URL#to_s` for more details.
Returns the computed URL for the document.
206 207 208 209 210 211 212 |
# File 'lib/jekyll/document.rb', line 206 def url @url ||= URL.new({ :template => url_template, :placeholders => url_placeholders, :permalink => permalink, }).to_s end |
#url_placeholders ⇒ Object
Construct a Hash of key-value pairs which contain a mapping between
a key in the URL template and the corresponding value for this document.
Returns the Hash of key-value pairs for replacement in the URL.
191 192 193 |
# File 'lib/jekyll/document.rb', line 191 def url_placeholders @url_placeholders ||= Drops::UrlDrop.new(self) end |
#url_template ⇒ Object
The URL template where the document would be accessible.
Returns the URL template for the document.
183 184 185 |
# File 'lib/jekyll/document.rb', line 183 def url_template collection.url_template end |
#write(dest) ⇒ Object
Write the generated Document file to the destination directory.
dest - The String path to the destination dir.
Returns nothing.
239 240 241 242 243 244 245 246 |
# File 'lib/jekyll/document.rb', line 239 def write(dest) path = destination(dest) FileUtils.mkdir_p(File.dirname(path)) Jekyll.logger.debug "Writing:", path File.write(path, output, :mode => "wb") trigger_hooks(:post_write) end |
#write? ⇒ Boolean
Determine whether this document should be written. Based on the Collection to which it belongs.
True if the document has a collection and if that collection’s #write? method returns true, and if the site’s Publisher will publish the document. False otherwise.
317 318 319 |
# File 'lib/jekyll/document.rb', line 317 def write? collection && collection.write? && site.publisher.publish?(self) end |
#yaml_file? ⇒ Boolean
Determine whether the document is a YAML file.
Returns true if the extname is either .yml or .yaml, false otherwise.
129 130 131 |
# File 'lib/jekyll/document.rb', line 129 def yaml_file? %w(.yaml .yml).include?(extname) end |