Class: Nanoc::Site

Inherits:
Object
  • Object
show all
Defined in:
lib/nanoc/base/source_data/site.rb,
lib/nanoc/helpers/capturing.rb

Overview

The in-memory representation of a nanoc site. It holds references to the following site data:

In addition, each site has a #config hash which stores the site configuration.

The physical representation of a Site is usually a directory that contains a configuration file, site data, a rakefile, a rules file, etc. The way site data is stored depends on the data source.

Constant Summary

DEFAULT_DATA_SOURCE_CONFIG =

The default configuration for a data source. A data source’s configuration overrides these options.

{
  :type         => 'filesystem_unified',
  :items_root   => '/',
  :layouts_root => '/',
  :config       => {}
}
DEFAULT_CONFIG =

The default configuration for a site. A site’s configuration overrides these options: when a Nanoc::Site is created with a configuration that lacks some options, the default value will be taken from DEFAULT_CONFIG.

{
  :text_extensions    => %w( css erb haml htm html js less markdown md php rb sass scss txt xhtml xml coffee hb handlebars mustache ms ).sort,
  :output_dir         => 'output',
  :data_sources       => [ {} ],
  :index_filenames    => [ 'index.html' ],
  :enable_output_diff => false,
  :prune              => { :auto_prune => false, :exclude => [ '.git', '.hg', '.svn', 'CVS' ] }
}

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Site) initialize(dir_or_config_hash)

Creates a site object for the site specified by the given dir_or_config_hash argument.

Parameters:

  • dir_or_config_hash (Hash, String)

    If a string, contains the path to the site directory; if a hash, contains the site configuration.



48
49
50
# File 'lib/nanoc/base/source_data/site.rb', line 48

def initialize(dir_or_config_hash)
  build_config(dir_or_config_hash)
end

Class Method Details

+ (String) config_filename_for_cwd

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns filename of the nanoc config file in the current working directory, or nil if there is none

Returns:

  • (String)

    filename of the nanoc config file in the current working directory, or nil if there is none



294
295
296
297
# File 'lib/nanoc/base/source_data/site.rb', line 294

def self.config_filename_for_cwd
  filenames = %w( nanoc.yaml config.yaml )
  filenames.find { |f| File.file?(f) }
end

+ (Boolean) cwd_is_nanoc_site?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true if the current working directory is a nanoc site, false otherwise

Returns:

  • (Boolean)

    true if the current working directory is a nanoc site, false otherwise



287
288
289
# File 'lib/nanoc/base/source_data/site.rb', line 287

def self.cwd_is_nanoc_site?
  !config_filename_for_cwd.nil?
end

Instance Method Details

- (Object) captures_store

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



61
62
63
# File 'lib/nanoc/helpers/capturing.rb', line 61

def captures_store
  @captures_store ||= CapturesStore.new
end

- (Object) captures_store_compiled_items

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



66
67
68
69
# File 'lib/nanoc/helpers/capturing.rb', line 66

def captures_store_compiled_items
  require 'set'
  @captures_store_compiled_items ||= Set.new
end

- (Array<Nanoc::CodeSnippet>) code_snippets

Returns this site’s code snippets.

Returns:



110
111
112
113
# File 'lib/nanoc/base/source_data/site.rb', line 110

def code_snippets
  load
  @code_snippets
end

- (void) compile

This method returns an undefined value.

Compiles the site.

Since:

  • 3.2.0



57
58
59
# File 'lib/nanoc/base/source_data/site.rb', line 57

def compile
  compiler.run
end

- (Nanoc::Compiler) compiler

Returns the compiler for this site. Will create a new compiler if none exists yet.

Returns:



65
66
67
# File 'lib/nanoc/base/source_data/site.rb', line 65

def compiler
  @compiler ||= Compiler.new(self)
end

- (Hash) config

Returns the site configuration. It has the following keys:

  • text_extensions (Array<String>) - A list of file extensions that will cause nanoc to threat the file as textual instead of binary. When the data source finds a content file with an extension that is included in this list, it will be marked as textual.

  • output_dir (String) - The directory to which compiled items will be written. This path is relative to the current working directory, but can also be an absolute path.

  • data_sources (Array<Hash>) - A list of data sources for this site. See below for documentation on the structure of this list. By default, there is only one data source of the filesystem type mounted at /.

  • index_filenames (Array<String>) - A list of filenames that will be stripped off full item paths to create cleaner URLs. For example, /about/ will be used instead of /about/index.html). The default value should be okay in most cases.

  • enable_output_diff (Boolean) - True when diffs should be generated for the compiled content of this site; false otherwise.

The list of data sources consists of hashes with the following keys:

  • :type (String) - The type of data source, i.e. its identifier.

  • :items_root (String) - The prefix that should be given to all items returned by the #items method (comparable to mount points for filesystems in Unix-ish OSes).

  • :layouts_root (String) - The prefix that should be given to all layouts returned by the #layouts method (comparable to mount points for filesystems in Unix-ish OSes).

  • :config (Hash) - A hash containing the configuration for this data source. nanoc itself does not use this hash. This is especially useful for online data sources; for example, a Twitter data source would need the username of the account from which to fetch tweets.

Returns:

  • (Hash)

    The site configuration



172
173
174
# File 'lib/nanoc/base/source_data/site.rb', line 172

def config
  @config
end

- (Array<Nanoc::DataSource>) data_sources

Returns the data sources for this site. Will create a new data source if none exists yet.

Returns:

Raises:



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
# File 'lib/nanoc/base/source_data/site.rb', line 77

def data_sources
  load_code_snippets

  @data_sources ||= begin
    @config[:data_sources].map do |data_source_hash|
      # Get data source class
      data_source_class = Nanoc::DataSource.named(data_source_hash[:type])
      raise Nanoc::Errors::UnknownDataSource.new(data_source_hash[:type]) if data_source_class.nil?

      # Warn about deprecated data sources
      # TODO [in nanoc 4.0] remove me
      case data_source_hash[:type]
      when 'filesystem'
        warn "Warning: the 'filesystem' data source has been renamed to 'filesystem_verbose'. Using 'filesystem' will work in nanoc 3.1.x, but it will likely not work anymore in a future release of nanoc. Please update your data source configuration and replace 'filesystem' with 'filesystem_verbose'."
      when 'filesystem_combined', 'filesystem_compact'
        warn "Warning: the 'filesystem_combined' and 'filesystem_compact' data source has been merged into the new 'filesystem_unified' data source. Using 'filesystem_combined' and 'filesystem_compact' will work in nanoc 3.1.x, but it will likely not work anymore in a future release of nanoc. Please update your data source configuration and replace 'filesystem_combined' and 'filesystem_compact with 'filesystem_unified'."
      end

      # Create data source
      data_source_class.new(
        self,
        data_source_hash[:items_root],
        data_source_hash[:layouts_root],
        data_source_hash.merge(data_source_hash[:config] || {})
      )
    end
  end
end

- (void) freeze

This method returns an undefined value.

Prevents all further modifications to itself, its items, its layouts etc.



217
218
219
220
221
222
# File 'lib/nanoc/base/source_data/site.rb', line 217

def freeze
  config.freeze_recursively
  items.each         { |i|  i.freeze  }
  layouts.each       { |l|  l.freeze  }
  code_snippets.each { |cs| cs.freeze }
end

- (Array<Nanoc::Item>) items

Returns this site’s items.

Returns:



118
119
120
121
# File 'lib/nanoc/base/source_data/site.rb', line 118

def items
  load
  @items
end

- (Array<Nanoc::Layouts>) layouts

Returns this site’s layouts.

Returns:

  • (Array<Nanoc::Layouts>)

    The list of layout in this site



126
127
128
129
# File 'lib/nanoc/base/source_data/site.rb', line 126

def layouts
  load
  @layouts
end

- (void) load

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Loads the site data. It is not necessary to call this method explicitly; it will be called when it is necessary.



236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
# File 'lib/nanoc/base/source_data/site.rb', line 236

def load
  return if @loaded || @loading
  @loading = true

  # Load all data
  load_code_snippets
  data_sources.each { |ds| ds.use }
  load_items
  load_layouts
  data_sources.each { |ds| ds.unuse }
  setup_child_parent_links

  # Ensure unique
  ensure_identifier_uniqueness(@items, 'item')
  ensure_identifier_uniqueness(@layouts, 'layout')

  # Load compiler too
  # FIXME this should not be necessary
  compiler.load

  @loaded = true
rescue => e
  unload
  raise e
ensure
  @loading = false
end

- (Object) load_data(force = false)

Deprecated.

It is no longer necessary to explicitly load site data. It is safe to remove all #load_data calls.



226
227
228
# File 'lib/nanoc/base/source_data/site.rb', line 226

def load_data(force = false)
  warn 'It is no longer necessary to call Nanoc::Site#load_data. This method no longer has any effect. All calls to this method can be safely removed.'
end

This method returns an undefined value.

Fills each item’s parent reference and children array with the appropriate items. It is probably not necessary to call this method manually; it will be called when appropriate.



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
# File 'lib/nanoc/base/source_data/site.rb', line 181

def setup_child_parent_links
  teardown_child_parent_links

  item_map = {}
  @items.each do |item|
    item_map[item.identifier] = item
  end

  @items.each do |item|
    parent_id_end = item.identifier.rindex('/', -2)
    if parent_id_end
      parent_id = item.identifier[0..parent_id_end]
      parent = item_map[parent_id]
      if parent
        item.parent = parent
        parent.children << item
      end
    end
  end
end

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Removes all child-parent links.



207
208
209
210
211
212
# File 'lib/nanoc/base/source_data/site.rb', line 207

def teardown_child_parent_links
  @items.each do |item|
    item.parent = nil
    item.children = []
  end
end

- (Object) unload

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Undoes the effects of #load. Used when #load raises an exception.



267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
# File 'lib/nanoc/base/source_data/site.rb', line 267

def unload
  return if @unloading
  @unloading = true

  @items_loaded = false
  @items = []
  @layouts_loaded = false
  @layouts = []
  @code_snippets_loaded = false
  @code_snippets = []

  compiler.unload

  @loaded = false
  @unloading = false
end