Class: Nanoc3::Site

Inherits:
Object
  • Object
show all
Defined in:
lib/nanoc3/base/site.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.

A site also has several helper classes:

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 Nanoc3::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 ),
  :output_dir         => 'output',
  :data_sources       => [ {} ],
  :index_filenames    => [ 'index.html' ],
  :enable_output_diff => false
}

Instance Attribute 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.

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

Parameters:

  • dir_or_config_hash (Hash, String) —

    If a string, contains the path



108
109
110
111
112
113
114
 
# File 'lib/nanoc3/base/site.rb', line 108

def initialize(dir_or_config_hash)
  build_config(dir_or_config_hash)

  @code_snippets_loaded = false
  @items_loaded         = false
  @layouts_loaded       = false
end

Instance Attribute Details

- (Hash) config (readonly)

The site configuration. The configuration 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



90
91
92
 
# File 'lib/nanoc3/base/site.rb', line 90

def config
  @config
end

- (Time) config_mtime (readonly)

modified

Returns:

  • (Time) —

    The timestamp when the site configuration was last



94
95
96
 
# File 'lib/nanoc3/base/site.rb', line 94

def config_mtime
  @config_mtime
end

- (Proc) preprocessor

loaded but before the site is compiled

Returns:

  • (Proc) —

    The code block that will be executed after all data is



101
102
103
 
# File 'lib/nanoc3/base/site.rb', line 101

def preprocessor
  @preprocessor
end

- (Time) rules_mtime (readonly)

The timestamp when the rules were last modified

Returns:

  • (Time) —

    The timestamp when the rules were last modified



97
98
99
 
# File 'lib/nanoc3/base/site.rb', line 97

def rules_mtime
  @rules_mtime
end

Instance Method Details

- (Array<Nanoc3::CodeSnippet>) code_snippets

Returns this site’s code snippets.

site

been loaded yet (call #load_data to load the site data)

Returns:

Raises:



199
200
201
202
 
# File 'lib/nanoc3/base/site.rb', line 199

def code_snippets
  raise Nanoc3::Errors::DataNotYetAvailable.new('Code snippets', false) unless @code_snippets_loaded
  @code_snippets
end

- (Nanoc3::Compiler) compiler

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

Returns:



120
121
122
 
# File 'lib/nanoc3/base/site.rb', line 120

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

- (Array<Nanoc3::DataSource>) data_sources

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

site

specifies an unknown data source

Returns:

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/nanoc3/base/site.rb', line 132

def data_sources
  @data_sources ||= begin
    @config[:data_sources].map do |data_source_hash|
      # Get data source class
      data_source_class = Nanoc3::DataSource.named(data_source_hash[:type])
      raise Nanoc3::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[:config] || {}
      )
    end
  end
end

- (Array<Nanoc3::Item>) items

Returns this site’s items.

been loaded yet (call #load_data to load the site data)

Returns:

Raises:



210
211
212
213
 
# File 'lib/nanoc3/base/site.rb', line 210

def items
  raise Nanoc3::Errors::DataNotYetAvailable.new('Items', true) unless @items_loaded
  @items
end

- (Array<Nanoc3::Layouts>) layouts

Returns this site’s layouts.

been loaded yet (call #load_data to load the site data)

Returns:

  • (Array<Nanoc3::Layouts>) —

    The list of layout in this site

Raises:



221
222
223
224
 
# File 'lib/nanoc3/base/site.rb', line 221

def layouts
  raise Nanoc3::Errors::DataNotYetAvailable.new('Layouts', true) unless @layouts_loaded
  @layouts
end

- (void) load_data(force = false)

This method returns an undefined value.

Loads the site data. This will query the DataSource associated with the site and fetch all site data. The site data is cached, so calling this method will not have any effect the second time, unless the force parameter is true.

has been loaded before, to circumvent caching issues

Parameters:

  • force (Boolean) (defaults to: false) —

    If true, will force load the site data even if it



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/nanoc3/base/site.rb', line 168

def load_data(force=false)
  # Don't load data twice
  return if instance_variable_defined?(:@data_loaded) && @data_loaded && !force

  # Load all data
  load_code_snippets(force)
  data_sources.each { |ds| ds.use }
  load_rules
  load_items
  load_layouts
  data_sources.each { |ds| ds.unuse }

  # Preprocess
  setup_child_parent_links
  preprocessor_context.instance_eval(&preprocessor) unless preprocessor.nil?
  link_everything_to_site
  setup_child_parent_links
  build_reps
  route_reps

  # Done
  @data_loaded = true
end