bridgetown-core 0.15.0.beta3 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +4 -4
  2. data/Rakefile +14 -0
  3. data/bridgetown-core.gemspec +3 -0
  4. data/lib/bridgetown-core.rb +6 -1
  5. data/lib/bridgetown-core/commands/concerns/actions.rb +29 -23
  6. data/lib/bridgetown-core/commands/console.rb +12 -2
  7. data/lib/bridgetown-core/commands/serve.rb +5 -0
  8. data/lib/bridgetown-core/concerns/data_accessible.rb +19 -0
  9. data/lib/bridgetown-core/concerns/layout_placeable.rb +17 -0
  10. data/lib/bridgetown-core/concerns/liquid_renderable.rb +20 -0
  11. data/lib/bridgetown-core/concerns/publishable.rb +10 -0
  12. data/lib/bridgetown-core/concerns/site/configurable.rb +62 -31
  13. data/lib/bridgetown-core/concerns/site/content.rb +88 -29
  14. data/lib/bridgetown-core/concerns/site/extensible.rb +15 -12
  15. data/lib/bridgetown-core/concerns/site/processable.rb +12 -10
  16. data/lib/bridgetown-core/concerns/site/renderable.rb +22 -2
  17. data/lib/bridgetown-core/concerns/site/writable.rb +16 -2
  18. data/lib/bridgetown-core/concerns/validatable.rb +59 -0
  19. data/lib/bridgetown-core/configuration.rb +1 -0
  20. data/lib/bridgetown-core/converter.rb +34 -0
  21. data/lib/bridgetown-core/converters/erb_templates.rb +78 -0
  22. data/lib/bridgetown-core/converters/markdown.rb +6 -23
  23. data/lib/bridgetown-core/converters/smartypants.rb +0 -10
  24. data/lib/bridgetown-core/document.rb +8 -52
  25. data/lib/bridgetown-core/drops/document_drop.rb +9 -1
  26. data/lib/bridgetown-core/errors.rb +2 -0
  27. data/lib/bridgetown-core/excerpt.rb +1 -6
  28. data/lib/bridgetown-core/filters.rb +2 -0
  29. data/lib/bridgetown-core/layout.rb +24 -1
  30. data/lib/bridgetown-core/liquid_renderer/file_system.rb +1 -1
  31. data/lib/bridgetown-core/page.rb +34 -25
  32. data/lib/bridgetown-core/plugin_manager.rb +14 -5
  33. data/lib/bridgetown-core/regenerator.rb +1 -1
  34. data/lib/bridgetown-core/renderer.rb +38 -12
  35. data/lib/bridgetown-core/ruby_template_view.rb +98 -0
  36. data/lib/bridgetown-core/tags/class_map.rb +90 -0
  37. data/lib/bridgetown-core/tags/include.rb +2 -0
  38. data/lib/bridgetown-core/tags/render_content.rb +11 -1
  39. data/lib/bridgetown-core/tags/webpack_path.rb +19 -22
  40. data/lib/bridgetown-core/utils.rb +53 -0
  41. data/lib/bridgetown-core/version.rb +2 -2
  42. data/lib/site_template/bridgetown.config.yml +5 -3
  43. data/lib/site_template/src/_components/{footer.html → footer.liquid} +0 -0
  44. data/lib/site_template/src/_components/{head.html → head.liquid} +0 -0
  45. data/lib/site_template/src/_components/{navbar.html → navbar.liquid} +0 -0
  46. data/lib/site_template/src/_layouts/{default.html → default.liquid} +1 -1
  47. data/lib/site_template/src/_layouts/{home.html → home.liquid} +0 -0
  48. data/lib/site_template/src/_layouts/{page.html → page.liquid} +0 -0
  49. data/lib/site_template/src/_layouts/{post.html → post.liquid} +0 -0
  50. metadata +59 -10
  51. data/lib/bridgetown-core/concerns/convertible.rb +0 -235
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0731d836363a7cc613e8a42a833fb1d45e50f293558cd78238d9b214b73e2d99
4
- data.tar.gz: 2597ac785d145bcd26083d08e803d4f0937165d8150bfb05eea5b9ba90ad6e4f
3
+ metadata.gz: d35a1d7fa1834831d59b4b7dfd072d3cddfb8d152416b63686aa1bf477567394
4
+ data.tar.gz: c3b2f423702f55e433709d11de4219f7ed76736f707b39aed0b22f09048b2804
5
5
  SHA512:
6
- metadata.gz: 7bead893392ffe25b85bcef0419201fa5a8752793f9b8812ac26e512ab35e2638d888ec02c64c672e7930c509afbe0fffa2c98b40316351028951469e63c9310
7
- data.tar.gz: e8083bd29fb64deef6f0fe17b028cb1aa373944cfcb15fe0ce686b03f6db6e12bcdbcb25842e4a508b2979facb9655cfe358fac685f7c2af4c44e2a6edb65c1c
6
+ metadata.gz: 9c7799ef500f1d6b519e4f0ede9487c37bde860b12250c1bd39bfe66a348729e73aa7256e04f84fa310e6a82f5b0fcd6041026d4f1f16c8528808ea5331cd4d8
7
+ data.tar.gz: 040dcffce2be2cdf189fd7dc1d5585f14a24975e5ee19b2e2d1aa88a09b4e011725727c127c3c2b690e09a79415e0d8edc9e5ce471d87b13b5cc3f4007cbbc50
data/Rakefile CHANGED
@@ -12,3 +12,17 @@ Rake::TestTask.new(:test) do |test|
12
12
  test.pattern = "test/**/test_*.rb"
13
13
  test.verbose = true
14
14
  end
15
+
16
+ require 'yard'
17
+ YARD::Rake::YardocTask.new(:yard) do |t|
18
+ t.files = ['lib/**/*.rb']
19
+ t.options = ['--no-output']
20
+ t.stats_options = ['--list-undoc']
21
+ end
22
+
23
+ namespace :yard do
24
+ task :serve do
25
+ port = ENV['YARD_PORT'] || "8808"
26
+ sh("yard server --reload -p #{port}")
27
+ end
28
+ end
@@ -33,7 +33,9 @@ Gem::Specification.new do |s|
33
33
 
34
34
  s.add_runtime_dependency("activesupport", "~> 6.0")
35
35
  s.add_runtime_dependency("addressable", "~> 2.4")
36
+ s.add_runtime_dependency("awesome_print", "~> 1.8")
36
37
  s.add_runtime_dependency("colorator", "~> 1.0")
38
+ s.add_runtime_dependency("erubi", "~> 1.9")
37
39
  s.add_runtime_dependency("faraday", "~> 1.0")
38
40
  s.add_runtime_dependency("faraday_middleware", "~> 1.0")
39
41
  s.add_runtime_dependency("i18n", "~> 1.0")
@@ -48,4 +50,5 @@ Gem::Specification.new do |s|
48
50
  s.add_runtime_dependency("safe_yaml", "~> 1.0")
49
51
  s.add_runtime_dependency("terminal-table", "~> 1.8")
50
52
  s.add_runtime_dependency("thor", "~> 1.0")
53
+ s.add_runtime_dependency("tilt", "~> 2.0")
51
54
  end
@@ -54,7 +54,7 @@ module Bridgetown
54
54
  autoload :Cleaner, "bridgetown-core/cleaner"
55
55
  autoload :Collection, "bridgetown-core/collection"
56
56
  autoload :Configuration, "bridgetown-core/configuration"
57
- autoload :Convertible, "bridgetown-core/concerns/convertible"
57
+ autoload :DataAccessible, "bridgetown-core/concerns/data_accessible"
58
58
  autoload :Deprecator, "bridgetown-core/deprecator"
59
59
  autoload :Document, "bridgetown-core/document"
60
60
  autoload :EntryFilter, "bridgetown-core/entry_filter"
@@ -64,6 +64,7 @@ module Bridgetown
64
64
  autoload :FrontmatterDefaults, "bridgetown-core/frontmatter_defaults"
65
65
  autoload :Hooks, "bridgetown-core/hooks"
66
66
  autoload :Layout, "bridgetown-core/layout"
67
+ autoload :LayoutPlaceable, "bridgetown-core/concerns/layout_placeable"
67
68
  autoload :Cache, "bridgetown-core/cache"
68
69
  autoload :CollectionReader, "bridgetown-core/readers/collection_reader"
69
70
  autoload :DataReader, "bridgetown-core/readers/data_reader"
@@ -77,17 +78,21 @@ module Bridgetown
77
78
  autoload :PageWithoutAFile, "bridgetown-core/page_without_a_file"
78
79
  autoload :PathManager, "bridgetown-core/path_manager"
79
80
  autoload :PluginManager, "bridgetown-core/plugin_manager"
81
+ autoload :Publishable, "bridgetown-core/concerns/publishable"
80
82
  autoload :Publisher, "bridgetown-core/publisher"
81
83
  autoload :Reader, "bridgetown-core/reader"
82
84
  autoload :Regenerator, "bridgetown-core/regenerator"
83
85
  autoload :RelatedPosts, "bridgetown-core/related_posts"
84
86
  autoload :Renderer, "bridgetown-core/renderer"
87
+ autoload :LiquidRenderable, "bridgetown-core/concerns/liquid_renderable"
85
88
  autoload :LiquidRenderer, "bridgetown-core/liquid_renderer"
89
+ autoload :RubyTemplateView, "bridgetown-core/ruby_template_view"
86
90
  autoload :LogWriter, "bridgetown-core/log_writer"
87
91
  autoload :Site, "bridgetown-core/site"
88
92
  autoload :StaticFile, "bridgetown-core/static_file"
89
93
  autoload :URL, "bridgetown-core/url"
90
94
  autoload :Utils, "bridgetown-core/utils"
95
+ autoload :Validatable, "bridgetown-core/concerns/validatable"
91
96
  autoload :VERSION, "bridgetown-core/version"
92
97
  autoload :Watcher, "bridgetown-core/watcher"
93
98
 
@@ -8,6 +8,11 @@ require "active_support/core_ext/string/indent"
8
8
  module Bridgetown
9
9
  module Commands
10
10
  module Actions
11
+ GITHUB_REGEX = %r!https://github\.com!.freeze
12
+ GITHUB_TREE_REGEX = %r!#{GITHUB_REGEX}/.*/.*/tree/.*/?!.freeze
13
+ GITHUB_BLOB_REGEX = %r!#{GITHUB_REGEX}/.*/.*/blob/!.freeze
14
+ GITHUB_REPO_REGEX = %r!github\.com/(.*?/[^/]*)!.freeze
15
+
11
16
  def create_builder(filename, data = nil)
12
17
  say_status :create_builder, filename
13
18
  data ||= yield if block_given?
@@ -89,35 +94,36 @@ module Bridgetown
89
94
  end
90
95
 
91
96
  # TODO: option to download and confirm remote automation?
97
+ # rubocop:disable Metrics/MethodLength
92
98
  def transform_automation_url(arg)
93
99
  return arg unless arg.start_with?("http")
94
100
 
95
101
  remote_file = determine_remote_filename(arg)
102
+ github_match = GITHUB_REGEX.match(arg)
103
+
104
+ arg = if arg.start_with?("https://gist.github.com")
105
+ arg.sub(
106
+ "https://gist.github.com", "https://gist.githubusercontent.com"
107
+ ) + "/raw"
108
+ elsif github_match
109
+ new_url = arg.sub(GITHUB_REGEX, "https://raw.githubusercontent.com")
110
+ github_tree_match = GITHUB_TREE_REGEX.match(arg)
111
+ github_blob_match = GITHUB_BLOB_REGEX.match(arg)
112
+
113
+ if github_tree_match
114
+ new_url.sub("/tree/", "/")
115
+ elsif github_blob_match
116
+ new_url.sub("/blob/", "/")
117
+ else
118
+ "#{new_url}/#{Bridgetown::Utils.default_github_branch_name(arg)}"
119
+ end
120
+ else
121
+ arg
122
+ end
96
123
 
97
- github_regex = %r!https://github\.com!
98
- github_tree_regex = %r!#{github_regex}/.*/.*/tree/.*/?!
99
-
100
- github_match = github_regex.match(arg)
101
- github_tree_match = github_tree_regex.match(arg)
102
-
103
- if arg.start_with?("https://gist.github.com")
104
- return arg.sub(
105
- "https://gist.github.com", "https://gist.githubusercontent.com"
106
- ) + "/raw/#{remote_file}"
107
- elsif github_match
108
- new_url = arg.sub(github_regex, "https://raw.githubusercontent.com")
109
-
110
- if github_tree_match
111
- new_url = new_url.sub("/tree/", "/")
112
- else
113
- new_url += "/master"
114
- end
115
-
116
- return "#{new_url}/#{remote_file}"
117
- end
118
-
119
- arg + "/#{remote_file}"
124
+ "#{arg}/#{remote_file}"
120
125
  end
126
+ # rubocop:enable Metrics/MethodLength
121
127
  end
122
128
  end
123
129
  end
@@ -1,7 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "irb"
4
-
5
3
  module Bridgetown
6
4
  module Commands
7
5
  class Console < Thor::Group
@@ -21,11 +19,17 @@ module Bridgetown
21
19
  type: :array,
22
20
  banner: "FILE1 FILE2",
23
21
  desc: "Custom configuration file(s)"
22
+ class_option :"bypass-ap",
23
+ type: :boolean,
24
+ desc: "Don't load AwesomePrint when IRB opens"
24
25
  class_option :blank,
25
26
  type: :boolean,
26
27
  desc: "Skip reading content and running generators before opening console"
27
28
 
28
29
  def console
30
+ require "irb"
31
+ require "awesome_print" unless options[:"bypass-ap"]
32
+
29
33
  Bridgetown.logger.info "Starting:", "Bridgetown v#{Bridgetown::VERSION.magenta}" \
30
34
  " (codename \"#{Bridgetown::CODE_NAME.yellow}\")" \
31
35
  " console…"
@@ -56,6 +60,12 @@ module Bridgetown
56
60
 
57
61
  begin
58
62
  catch(:IRB_EXIT) do
63
+ unless options[:"bypass-ap"]
64
+ AwesomePrint.defaults = {
65
+ indent: 2,
66
+ }
67
+ AwesomePrint.irb!
68
+ end
59
69
  irb.eval_input
60
70
  end
61
71
  end
@@ -29,6 +29,11 @@ module Bridgetown
29
29
  class_option :skip_initial_build,
30
30
  type: :boolean,
31
31
  desc: "Skips the initial site build which occurs before the server is started."
32
+ class_option :watch,
33
+ type: :boolean,
34
+ aliases: "-w",
35
+ default: true,
36
+ desc: "Watch for changes and rebuild"
32
37
 
33
38
  def self.banner
34
39
  "bridgetown serve [options]"
@@ -0,0 +1,19 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Bridgetown
4
+ module DataAccessible
5
+ # Returns the contents as a String.
6
+ def to_s
7
+ output || content || ""
8
+ end
9
+
10
+ # Accessor for data properties by Liquid.
11
+ #
12
+ # property - The String name of the property to retrieve.
13
+ #
14
+ # Returns the String value or nil if the property isn't included.
15
+ def [](property)
16
+ data[property]
17
+ end
18
+ end
19
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Bridgetown
4
+ module LayoutPlaceable
5
+ # Determine whether the file should be placed into layouts.
6
+ #
7
+ # Returns false if the document is an asset file or if the front matter
8
+ # specifies `layout: none`
9
+ def place_in_layout?
10
+ !(yaml_file? || no_layout?)
11
+ end
12
+
13
+ def no_layout?
14
+ data["layout"] == "none"
15
+ end
16
+ end
17
+ end
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Bridgetown
4
+ module LiquidRenderable
5
+ # Determine whether the file should be rendered with Liquid.
6
+ #
7
+ # Returns false if the document is a yaml file or if the document doesn't
8
+ # contain any Liquid Tags or Variables, true otherwise.
9
+ def render_with_liquid?
10
+ return false if data["render_with_liquid"] == false
11
+
12
+ !(yaml_file? || !Utils.has_liquid_construct?(content))
13
+ end
14
+
15
+ # Override in individual classes
16
+ def yaml_file?
17
+ false
18
+ end
19
+ end
20
+ end
@@ -0,0 +1,10 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Bridgetown
4
+ module Publishable
5
+ # Whether the file is published or not, as indicated in YAML front-matter
6
+ def published?
7
+ !(data.key?("published") && data["published"] == false)
8
+ end
9
+ end
10
+ end
@@ -2,12 +2,17 @@
2
2
 
3
3
  module Bridgetown
4
4
  module Site::Configurable
5
- # Public: Set the site's configuration. This handles side-effects caused by
5
+ # Set the site's configuration. This handles side-effects caused by
6
6
  # changing values in the configuration.
7
7
  #
8
- # config - a Bridgetown::Configuration, containing the new configuration.
8
+ # @param config [Bridgetown::Configuration]
9
+ # An instance of {Bridgetown::Configuration},
10
+ # containing the new configuration.
9
11
  #
10
- # Returns the new configuration.
12
+ # @return [Bridgetown::Configuration]
13
+ # A new instance of {Bridgetown::Configuration}
14
+ #
15
+ # @see Bridgetown::Configuration
11
16
  def config=(config)
12
17
  @config = config.clone
13
18
 
@@ -32,81 +37,107 @@ module Bridgetown
32
37
  @config
33
38
  end
34
39
 
35
- # Returns the FrontmatterDefaults or creates a new FrontmatterDefaults
36
- # if it doesn't already exist.
40
+ # Returns the current instance of {FrontmatterDefaults} or
41
+ # creates a new instance {FrontmatterDefaults} if it doesn't already exist.
37
42
  #
38
- # Returns The FrontmatterDefaults
43
+ # @return [FrontmatterDefaults]
44
+ # Returns an instance of {FrontmatterDefaults}
39
45
  def frontmatter_defaults
40
46
  @frontmatter_defaults ||= FrontmatterDefaults.new(self)
41
47
  end
42
48
 
43
- # Whether to perform a full rebuild without incremental regeneration
49
+ # Whether to perform a full rebuild without incremental regeneration.
50
+ # If either +override+["incremental"] or +config+["incremental"] are true,
51
+ # fully rebuild the site. If not, incrementally build the site.
44
52
  #
45
- # Returns a Boolean: true for a full rebuild, false for normal build
53
+ # @param [Hash] override
54
+ # An override hash to override the current config value
55
+ # @option override [Boolean] "incremental" Whether to incrementally build
56
+ # @return [Boolean] true for full rebuild, false for normal build
46
57
  def incremental?(override = {})
47
58
  override["incremental"] || config["incremental"]
48
59
  end
49
60
 
50
- # Returns the publisher or creates a new publisher if it doesn't
51
- # already exist.
61
+ # Returns the current instance of {Publisher} or creates a new instance of
62
+ # {Publisher} if one doesn't exist.
52
63
  #
53
- # Returns The Publisher
64
+ # @return [Publisher] Returns an instance of {Publisher}
54
65
  def publisher
55
66
  @publisher ||= Publisher.new(self)
56
67
  end
57
68
 
58
- # Public: Prefix a given path with the root directory.
69
+ # Prefix a path or paths with the {#root_dir} directory.
59
70
  #
60
- # paths - (optional) path elements to a file or directory within the
61
- # root directory
71
+ # @see Bridgetown.sanitized_path
72
+ # @param paths [Array<String>]
73
+ # An array of paths to prefix with the root_dir directory using the
74
+ # {Bridgetown.sanitized_path} method.
62
75
  #
63
- # Returns a path which is prefixed with the root_dir directory.
76
+ # @return [Array<String>] Return an array of updated paths if multiple paths given.
64
77
  def in_root_dir(*paths)
65
78
  paths.reduce(root_dir) do |base, path|
66
79
  Bridgetown.sanitized_path(base, path)
67
80
  end
68
81
  end
69
82
 
70
- # Public: Prefix a given path with the source directory.
71
- #
72
- # paths - (optional) path elements to a file or directory within the
73
- # source directory
83
+ # Prefix a path or paths with the {#source} directory.
74
84
  #
75
- # Returns a path which is prefixed with the source directory.
85
+ # @see Bridgetown.sanitized_path
86
+ # @param paths [Array<String>]
87
+ # An array of paths to prefix with the source directory using the
88
+ # {Bridgetown.sanitized_path} method.
89
+ # @return [Array<String>] Return an array of updated paths if multiple paths given.
76
90
  def in_source_dir(*paths)
77
91
  paths.reduce(source) do |base, path|
78
92
  Bridgetown.sanitized_path(base, path)
79
93
  end
80
94
  end
81
95
 
82
- # Public: Prefix a given path with the destination directory.
96
+ # Prefix a path or paths with the {#dest} directory.
83
97
  #
84
- # paths - (optional) path elements to a file or directory within the
85
- # destination directory
98
+ # @see Bridgetown.sanitized_path
99
+ # @param paths [Array<String>]
100
+ # An array of paths to prefix with the destination directory using the
101
+ # {Bridgetown.sanitized_path} method.
86
102
  #
87
- # Returns a path which is prefixed with the destination directory.
103
+ # @return [Array<String>] Return an array of updated paths if multiple paths given.
88
104
  def in_dest_dir(*paths)
89
105
  paths.reduce(dest) do |base, path|
90
106
  Bridgetown.sanitized_path(base, path)
91
107
  end
92
108
  end
93
109
 
94
- # Public: Prefix a given path with the cache directory.
110
+ # Prefix a path or paths with the {#cache_dir} directory.
95
111
  #
96
- # paths - (optional) path elements to a file or directory within the
97
- # cache directory
112
+ # @see Bridgetown.sanitized_path
113
+ # @param paths [Array<String>]
114
+ # An array of paths to prefix with the {#cache_dir} directory using the
115
+ # {Bridgetown.sanitized_path} method.
98
116
  #
99
- # Returns a path which is prefixed with the cache directory.
117
+ # @return [Array<String>] Return an array of updated paths if multiple paths given.
100
118
  def in_cache_dir(*paths)
101
119
  paths.reduce(cache_dir) do |base, path|
102
120
  Bridgetown.sanitized_path(base, path)
103
121
  end
104
122
  end
105
123
 
106
- # Public: The full path to the directory that houses all the collections registered
107
- # with the current site.
124
+ # The full path to the directory that houses all the registered collections
125
+ # for the current site.
126
+ #
127
+ # If +@collections_path+ is specified use its value.
128
+ #
129
+ # If +@collections+ is not specified and +config+["collections_dir"] is
130
+ # specified, prepend it with {#source} and assign it to
131
+ # {#collections_path}.
132
+ #
133
+ # If +@collections+ is not specified and +config+["collections_dir"] is not
134
+ # specified, assign {#source} to +@collections_path+
108
135
  #
109
- # Returns the source directory or the absolute path to the custom collections_dir
136
+ # @return [String] Returns the full path to the collections directory
137
+ # @see #config
138
+ # @see #source
139
+ # @see #collections_path
140
+ # @see #in_source_dir
110
141
  def collections_path
111
142
  dir_str = config["collections_dir"]
112
143
  @collections_path ||= dir_str.empty? ? source : in_source_dir(dir_str)
@@ -4,17 +4,24 @@ module Bridgetown
4
4
  module Site::Content
5
5
  # Construct a Hash of Posts indexed by the specified Post attribute.
6
6
  #
7
- # post_attr - The String name of the Post attribute.
7
+ # @param post_attr [String] The String name of the Post attribute.
8
8
  #
9
- # Examples
9
+ # @example
10
+ # Returns a hash like so: { attr => posts } where
11
+ #
12
+ # attr - One of the values for the requested attribute.
13
+ #
14
+ # posts - The Array of Posts with the given attr value.
15
+ #
16
+ # @example
10
17
  #
11
18
  # post_attr_hash('categories')
12
19
  # # => { 'tech' => [<Post A>, <Post B>],
13
20
  # # 'ruby' => [<Post B>] }
14
21
  #
15
- # Returns the Hash: { attr => posts } where
16
- # attr - One of the values for the requested attribute.
17
- # posts - The Array of Posts with the given attr value.
22
+ # @return [Hash{String, Symbol => Array<Post>}]
23
+ # Returns a hash of !{attr => posts}
24
+ #
18
25
  def post_attr_hash(post_attr)
19
26
  # Build a hash map based on the specified post attribute ( post attr =>
20
27
  # array of posts ) then sort each array in reverse order.
@@ -28,41 +35,85 @@ module Bridgetown
28
35
  end
29
36
  end
30
37
 
38
+ # Returns a hash of "tags" using {#post_attr_hash} where each tag is a key
39
+ # and each value is a post which contains the key.
40
+ # @example
41
+ # tags
42
+ # # => { 'tech': [<Post A>, <Post B>],
43
+ # # 'ruby': [<Post C> }
44
+ # @return [Hash{String, Array<Post>}] Returns a hash of all tags and their corresponding posts
45
+ # @see post_attr_hash
31
46
  def tags
32
47
  post_attr_hash("tags")
33
48
  end
34
49
 
50
+ # Returns a hash of "categories" using {#post_attr_hash} where each tag is
51
+ # a key and each value is a post which contains the key.
52
+ # @example
53
+ # categories
54
+ # # => { 'tech': [<Post A>, <Post B>],
55
+ # # 'ruby': [<Post C> }
56
+ # @return [Hash{String, Array<Post>}] Returns a hash of all categories and
57
+ # their corresponding posts
58
+ # @see post_attr_hash
35
59
  def categories
36
60
  post_attr_hash("categories")
37
61
  end
38
62
 
63
+ # Returns the value of +data+["site_metadata"] or creates a new instance of
64
+ # +ActiveSupport::HashWithIndifferentAccess+
65
+ # @return [Hash] Returns a hash of site metadata
39
66
  def metadata
40
67
  data["site_metadata"] ||= ActiveSupport::HashWithIndifferentAccess.new
41
68
  end
42
69
 
43
70
  # The Hash payload containing site-wide data.
44
71
  #
45
- # Returns the Hash: { "site" => data } where data is a Hash with keys:
46
- # "time" - The Time as specified in the configuration or the
47
- # current time if none was specified.
48
- # "posts" - The Array of Posts, sorted chronologically by post date
49
- # and then title.
50
- # "pages" - The Array of all Pages.
51
- # "html_pages" - The Array of HTML Pages.
52
- # "categories" - The Hash of category values and Posts.
53
- # See Site#post_attr_hash for type info.
54
- # "tags" - The Hash of tag values and Posts.
55
- # See Site#post_attr_hash for type info.
72
+ # @example
73
+ # site_payload
74
+ # # => { "site" => data } Where data is a Hash. See example below
75
+ #
76
+ # site = site_payload["site"]
77
+ # # => Returns a Hash with the following keys:
78
+ # #
79
+ # # site["time"] - The Time as specified in the configuration or the
80
+ # # current time if none was specified.
81
+ # #
82
+ # # site["posts"] - The Array of Posts, sorted chronologically by post date
83
+ # # and then title.
84
+ # #
85
+ # # site["pages"] - The Array of all Pages.
86
+ # #
87
+ # # site["html_pages"] - The Array of HTML Pages.
88
+ # #
89
+ # # site["categories"] - The Hash of category values and Posts.
90
+ # # See Site#post_attr_hash for type info.
91
+ # #
92
+ # # site["tags"] - The Hash of tag values and Posts.
93
+ # # See Site#post_attr_hash for type info.
94
+ #
95
+ # @return [Hash] Returns a hash in the structure of { "site" => data }
96
+ #
97
+ # See above example for usage.
98
+ #
99
+ # @see #post_attr_hash
56
100
  def site_payload
57
101
  Drops::UnifiedPayloadDrop.new self
58
102
  end
59
103
  alias_method :to_liquid, :site_payload
60
104
 
61
- # The list of collections and their corresponding Bridgetown::Collection instances.
62
- # If config['collections'] is set, a new instance is created
63
- # for each item in the collection, a new hash is returned otherwise.
105
+ # The list of {#collections} and their corresponding {Bridgetown::Collection} instances.
106
+ #
107
+ # If +config+['collections'] is set, a new instance of {Bridgetown::Collection} is created
108
+ # for each entry in the collections configuration.
109
+ #
110
+ # If +config+["collections"] is not specified, a blank hash is returned.
64
111
  #
65
- # Returns a Hash containing collection name-to-instance pairs.
112
+ # @return [Hash{String, Symbol => Bridgetown::Collection}] A Hash
113
+ # containing a collection name-to-instance pairs.
114
+ #
115
+ # @return [Hash] Returns a blank hash if no items found
116
+ # @see Collection
66
117
  def collections
67
118
  @collections ||= collection_names.each_with_object(
68
119
  ActiveSupport::HashWithIndifferentAccess.new
@@ -71,10 +122,11 @@ module Bridgetown
71
122
  end
72
123
  end
73
124
 
74
- # The list of collection names.
75
- #
76
- # Returns an array of collection names from the configuration,
77
- # or an empty array if the `collections` key is not set.
125
+ # An array of collection names.
126
+ # @return [Array<Collection>] an array of collection names from the configuration,
127
+ # or an empty array if the +config+["collections"] key is not set.
128
+ # @raise ArgumentError Raise an error if +config+["collections"] is not
129
+ # an Array or a Hash
78
130
  def collection_names
79
131
  case config["collections"]
80
132
  when Hash
@@ -88,22 +140,29 @@ module Bridgetown
88
140
  end
89
141
  end
90
142
 
91
- # Get all the documents
92
- #
93
- # Returns an Array of all Documents
143
+ # Get all documents.
144
+ # @return [Array<String>] an array of documents from the configuration
94
145
  def documents
95
146
  collections.each_with_object(Set.new) do |(_, collection), set|
96
147
  set.merge(collection.docs).merge(collection.files)
97
148
  end.to_a
98
149
  end
99
150
 
100
- # Get the to be written documents
151
+ # Get the documents to be written
101
152
  #
102
- # Returns an Array of Documents which should be written
153
+ # @return [Array<String, File>] an Array of Documents which should be written and
154
+ # that +respond_to :write?+
155
+ # @see #documents
156
+ # @see Collection
103
157
  def docs_to_write
104
158
  documents.select(&:write?)
105
159
  end
106
160
 
161
+ # Get all posts.
162
+ #
163
+ # @return [Collection] A #Collection of posts. Returns +#collections+["posts"]
164
+ # @return [Collection] Return a new #Collection if +#collections+["posts"] is nil
165
+ # @see Collection
107
166
  def posts
108
167
  collections["posts"] ||= Collection.new(self, "posts")
109
168
  end