d-mark 1.0.0a1 → 1.0.0b2

data/samples/identifiers-and-patterns.dmark

@@ -1,539 +0,0 @@
-p. In Nanoc, every item (page or asset) and every layout has a unique %firstterm{identifier}: a string derived from the file’s path. A %firstterm{pattern} is an expression that is used to select items or layouts based on their identifier.
-
-h2. Identifiers
-
-p. Identifiers come in two types: the %emph{full} type, new in Nanoc 4, and the %emph{legacy} type, used in Nanoc 3.
-
-dl.
-  dt. full
-  dd. An identifier with the full type is the filename, with the path to the content directory removed. For example, the file %filename{/Users/denis/stoneship/content/about.md} will have the full identifier %identifier{/about.md}.
-
-  dt. legacy
-  dd. An identifier with the legacy type is the filename, with the path to the content directory removed, the extension removed, and a slash appended. For example, the file %filename{/Users/denis/stoneship/content/about.md} will have the legacy identifier %identifier{/about/}. This corresponds closely with paths in clean URLs.
-
-p. The following methods are useful for full identifiers:
-
-dl.
-  dt. %code{identifier.without_ext} → %class{String}
-  dd. identifier with the last extension removed
-
-  dt. %code{identifier.without_exts} → %class{String}
-  dd. identifier with all extensions removed
-
-  dt. %code{identifier.ext} → %class{String}
-  dd. the last extension of this identifier
-
-  dt. %code{identifier.exts} → %class{String}
-  dd. all extensions of this identifier
-
-  dt. %code{identifier + string} → %class{String}
-  dd. identifier with the given string appended
-
-p. Here are some examples:
-
-listing[lang=ruby].
-  identifier = Nanoc::Identifier.new('/about.md')
-
-  identifier.without_ext
-  # => "/about"
-
-  identifier.ext
-  # => "md"
-
-p. The following method is useful for legacy identifiers:
-
-dl[legacy].
-  dt. %code{identifier.chop} → %class{String}
-  dd. identifier with the last character removed
-
-p. Here are some examples:
-
-listing[lang=ruby].
-  identifier = Nanoc::Identifier.new('/about/', type: :legacy)
-
-  identifier.chop
-  # => "/about"
-
-  identifier.chop + '.html'
-  # => "/about.html"
-
-  identifier + 'index.html'
-  # => "/about/index.html"
-
-h2. Patterns
-
-p. Patterns are used to find items and layouts based on their identifier. They come in three varieties:
-
-ul.
-  li. glob patterns
-  li. regular expression patterns
-  li. legacy patterns
-
-h3. Glob patterns
-
-p. Glob patterns are strings that contain wildcard characters. Wildcard characters are characters that can be substituted for other characters in a identifier. An example of a glob pattern is %glob{/projects/*.md}, which matches all files with a %filename{md} extension in the %filename{/projects} directory.
-
-p. Globs are commonplace in Unix-like environments. For example, the Unix command for listing all files with the %filename{md} extension in the current directory is %command{ls *.md}. In this example, the argument to the %command{ls} command is a wildcard.
-
-p. Nanoc supports the following wildcards in glob patterns:
-
-dl.
-  dt. %code{*}
-  dd. Matches any file or directory name. Does not cross directory boundaries. For example, %glob{/projects/*.md} matches %identifier{/projects/nanoc.md}, but not %identifier{/projects/cri.adoc} nor %identifier{/projects/nanoc/about.md}.
-
-  dt. %code{**/}
-  dd. Matches zero or more levels of nested directories. For example, %glob{/projects/**/*.md} matches both %identifier{/projects/nanoc.md} and %identifier{/projects/nanoc/history.md}.
-
-  dt. %code{?}
-  dd. Matches a single character.
-
-  dt. %code{[abc]}
-  dd. Matches any single character in the set. For example, %glob{/people/[kt]im.md} matches only %identifier{/people/kim.md} and %identifier{/people/tim.md}.
-
-  dt. %code{{foo,bar%}}
-  dd. Matches either string in the comma-separated list. More than two strings are possible. For example, %glob{/c{at,ub,ount%}s.txt} matches %identifier{/cats.txt}, %identifier{/cubs.txt} and %identifier{/counts.txt}, but not %identifier{/cabs.txt}.
-
-p. A glob pattern that matches every item is %glob{/**/*}. A glob pattern that matches every item/layout with the extension %filename{md} is %glob{/**/*.md}.
-
-h3. Regular expression patterns
-
-p. You can use a regular expression to select items and layouts.
-
-p. For matching identifiers, the %code{%%r{…%}} syntax is (arguably) nicer than the %code{/…/} syntax. The latter is not a good fit for identifiers (or filenames), because all slashes need to be escaped. The %code{\A} and %code{\z} anchors are also useful to make sure the entire identifier is matched.
-
-p. An example of a regular expression pattern is %code{%%r{\A/projects/(cri|nanoc)\.md\z%}}, which matches both %identifier{/projects/nanoc.md} and %identifier{/projects/cri.md}.
-
-h3. Legacy patterns
-
-p. Legacy patterns are strings that contain wildcard characters. The wildcard characters behave differently than the glob wildcard characters.
-
-p. To enable legacy patterns, set %code{string_pattern_type} to %code{"legacy"} in the configuration. For example:
-
-listing[lang=yaml].
-  string_pattern_type: "legacy"
-
-p. For legacy patterns, Nanoc supports the following wildcards:
-
-dl.
-  dt. %code{*}
-  dd. Matches zero or more characters, including a slash. For example, %glob{/projects/*/} matches %glob{/projects/nanoc/} and %identifier{/projects/nanoc/about/}, but not %identifier{/projects/}.
-
-  dt. %code{+}
-  dd. Matches one or more characters, including a slash. For example, %glob{/projects/+} matches %identifier{/projects/nanoc/} and %identifier{/projects/nanoc/about/}, but not %identifier{/projects/}.
-
-p. Install Nanoc using RubyGems:
-
-listing.
-  %prompt{%%} %kbd{gem install nanoc}
-
-note. %entity{sudo-gem-install}
-
-p. After installing, head over to %ref[item=/doc/tutorial.*]{}! For detailed installation instructions, read on.
-
-h2. Installing Ruby
-
-p. Nanoc requires %ref[url=http://ruby-lang.org/]{Ruby} in order to run. Nanoc supports the official Ruby interpreter from version 2.1 up, as well as JRuby from version 9000 up.
-
-p. Ruby may already be installed on your system. To check, open a terminal window and type %kbd{ruby --version}. If you get “command not found”, Ruby is not yet installed. Otherwise, you will see which version of Ruby you have:
-
-listing.
-  %prompt{%%} %kbd{ruby --version}
-  %erb{config[:ruby_version_info]}
-  %prompt{%%}
-
-p. To install Ruby, follow the %ref[url=https://www.ruby-lang.org/en/documentation/installation/]{installation instructions on the Ruby web site}.
-
-h2. Installing Nanoc
-
-p. All dependencies are now taken care of, and installing Nanoc should now be easy:
-
-listing.
-  %prompt{%%} %kbd{gem install nanoc}
-
-note. %entity{sudo-gem-install}
-
-p. To make sure that Nanoc was installed correctly, run %kbd{nanoc --version}. It should print the version number along with some other information, like this:
-
-listing.
-  %prompt{%%} %kbd{nanoc --version}
-  %erb{config[:nanoc_version_info]}
-  %prompt{%%}
-
-p. If you get a “command not found” error when trying to run %command{nanoc}, you might have to adjust your %code{$PATH} to include the path to the directory where RubyGems installs executables.
-
-p. The current version of Nanoc is is %erb{latest_release_info[:version]}, released on %erb{latest_release_info[:date].format_as_date}. You can find the release notes for this version as well as release notes for older versions on %ref[item=/release-notes]{}.
-
-p. If you’re on Windows and are using the Windows console, it’s probably a good idea to install the %productname{win32console} gem using %kbd{gem install win32console} to allow Nanoc to use pretty colors when writing stuff to the terminal.
-
-h3. Installing from git
-
-p. You can also install Nanoc from the repository if you want to take advantage of the latest features and improvements in Nanoc. Be warned that the versions from the repository may be unstable, so it is recommended to install Nanoc from RubyGems if you want to stay safe. You can install Nanoc from the git repository like this:
-
-listing.
-  %prompt{~%%} %kbd{git clone git://github.com/nanoc/nanoc.git}
-  %prompt{~%%} %kbd{cd nanoc}
-  %prompt{~/nanoc%%} %kbd{gem build nanoc.gemspec}
-  %prompt{~/nanoc%%} %kbd{gem install nanoc-*.gem}
-
-p. Nanoc 4 takes a clean break from the past, removing anything that was holding back future development.
-
-p. The good news is that Nanoc 4.0 is quite similar to 3.8. Upgrading a Nanoc 3.x site to Nanoc 4.0 only takes minutes.
-
-h2. Why upgrade?
-
-ul[spacious].
-  li. Nanoc 4 brings identifiers with extensions, and thereby solves a long-standing usability issue. It also introduces glob patterns, which makes rules easier to write.
-
-  li. Nanoc 4 paves the way for new features and performance improvements. Nanoc 3 exposed its internals in a public API, making it hard to make significant changes.
-
-  li. Nanoc 3 is in maintenance mode, which means it will only get critical bug fixes.
-
-h2. Installing Nanoc 4
-
-p. Before installing, ensure you have a supported version of Ruby. Nanoc supports Ruby 2.2 and up, and JRuby 9000 and up:
-
-listing.
-  %prompt{%%} %kbd{ruby --version}
-  %erb{config[:ruby_version_info]}
-  %prompt{%%}
-
-p. To upgrade Ruby, follow the %ref[url=https://www.ruby-lang.org/en/documentation/installation/]{installation instructions on the Ruby web site}.
-
-p. You can install Nanoc 4 using RubyGems:
-
-listing.
-  %prompt{%%} %kbd{gem install nanoc}
-
-note. %entity{sudo-gem-install}
-
-p. We recommend using %ref[url=http://bundler.io/]{Bundler} to manage dependencies. When using Bundler, ensure there is a line for Nanoc in the %filename{Gemfile} that looks like this:
-
-listing[lang=ruby].
-  gem 'nanoc', '~> 4.0'
-
-h2[id=quick-upgrade-guide]. Quick upgrade guide
-
-p. The following steps will get a Nanoc 3 site working on Nanoc 4 with a minimal amount of changes.
-
-ol[spacious].
-  li. Change mentions of %code{Nanoc3} to %code{Nanoc}.
-
-  li. Change mentions of %code{@site.config} to %code{@config}.
-
-  li. Add %code{identifier_type: legacy} to the individual data source configurations. For example:
-
-    listing[lang=yaml,legacy].
-      data_sources:
-        -
-          type: filesystem
-
-    listing[lang=yaml,new].
-      data_sources:
-        -
-          type: filesystem
-          identifier_type: legacy
-
-  li. Add %code{string_pattern_type: legacy} to the configuration file. For example:
-
-    listing[lang=yaml,legacy].
-      data_sources:
-        -
-          type: filesystem
-          identifier_type: legacy
-
-    listing[lang=yaml,new].
-      string_pattern_type: legacy
-      data_sources:
-        -
-          type: filesystem
-          identifier_type: legacy
-
-  li. In Rules, remove the %code{rep.} prefix from %code{filter}, %code{layout} and %code{snapshot}. For example:
-
-    listing[lang=ruby,legacy].
-      compile '*' do
-        rep.filter :erb
-        rep.layout 'default'
-      end
-
-    listing[lang=ruby,new].
-      compile '*' do
-        filter :erb
-        layout 'default'
-      end
-
-  li. In the %code{preprocess} block, use %code{@items.create} rather than instantiating %code{Nanoc::Item}. For example:
-
-    listing[lang=ruby,legacy].
-      @items << Nanoc::Item.new('Hello', {%}, '/hello/')
-
-    listing[lang=ruby,new].
-      @items.create('Hello', {%}, '/hello/')
-
-  li. In data sources, use %code{#new_item} or %code{#new_layout} rather than instantiating %code{Nanoc::Item} or %code{Nanoc::Layout}. For example:
-
-    listing[lang=ruby,legacy].
-      def items
-        [Nanoc::Item.new('Hello', {%}, '/hello/')]
-      end
-
-    listing[lang=ruby,new].
-      def items
-        [new_item('Hello', {%}, '/hello/')]
-      end
-
-  li. Replace %code{.reps[0]} by %code{.reps[:default]}. For example:
-
-    listing[lang=ruby,legacy].
-      item.reps[0].path
-
-    listing[lang=ruby,new].
-      item.reps[:default].path
-
-  li. Replace calls to %code{#rep_named} by %code{reps[%var{something}]}, where %var{something} is the argument to %code{#rep_named}. For example:
-
-    listing[lang=ruby,legacy].
-      item.rep_named(:raw).path
-
-    listing[lang=ruby,new].
-      item.reps[:raw].path
-
-  li. If you use the static data source, disable it for now and follow the extended upgrade instructions below.
-
-h2. Extended upgrade guide
-
-p. This section describes how to upgrade a site to identifiers with extensions and glob patterns. For details, see %ref[item=/doc/identifiers-and-patterns.*]{}.
-
-p. This section assumes you have already upgraded the site following the instructions in %ref[frag=quick-upgrade-guide]{} above.
-
-p. Before you start, add %code{enable_output_diff: true} to the configuration file. This will let the %command{compile} command write out a diff with the changes to the compiled output. This diff will allow you to verify that no unexpected changes occur.
-
-tip. If you use a filter that minifies HTML content, such as %code{html5small}, we recommend turning it off before upgrading the site, so that the output diff becomes easier to read.
-
-h3. Enabling glob patterns
-
-p. Before enabling them, ensure you are familiar with glob patterns. For details, see %ref[item=/doc/identifiers-and-patterns.*,frag=glob-patterns]{}.
-
-p. To use glob patterns:
-
-ol[spacious].
-  li. Set %code{string_pattern_type} to %code{glob} in the configuration file. For example:
-
-    listing[lang=yaml,legacy].
-      string_pattern_type: legacy
-
-    listing[lang=yaml,new].
-      string_pattern_type: glob
-
-  li. Ensure that all string patterns in the %filename{Rules} file, as well as in calls to %code{@items[…]}, %code{@layouts[…]}, and %code{#render} throughout the site, start and end with a slash. This is an intermediate step. For example:
-
-    listing[lang=ruby,legacy].
-      # Before
-      compile 'articles/*' do
-        layout 'default'
-      end
-
-    listing[lang=ruby,legacy].
-      # After
-      compile '/articles/*/' do
-        layout '/default/'
-      end
-
-    listing[lang=ruby,legacy].
-      # Before
-      @items['foo']
-      @layouts['/bar']
-
-    listing[lang=ruby,legacy].
-      # After
-      @items['/foo/']
-      @layouts['/bar/']
-
-    listing[lang=rhtml,legacy].
-      <!-- Before -->
-      <%%= render 'header' %%>
-
-    listing[lang=rhtml,legacy].
-      <!-- After -->
-      <%%= render '/header/' %%>
-
-  li. Replace %code{*} and %code{+} with %code{**/*} in all string patterns in the %filename{Rules} file, as well as in calls to %code{@items[…]}, %code{@layouts[…]}, and %code{#render} throughout the site. For example:
-
-    listing[lang=ruby,legacy].
-      compile '/articles/*/' do
-        layout '/default/'
-      end
-
-    listing[lang=ruby,new].
-      compile '/articles/**/*/' do
-        layout '/default/'
-      end
-
-    listing[lang=ruby,legacy].
-      @items['/articles/*/']
-
-    listing[lang=ruby,new].
-      @items['/articles/**/*/']
-
-p. This approach should work out of the box: Nanoc should not raise errors and the output diff should be empty.
-
-h3. Enabling identifiers with extensions
-
-note. This section assumes that glob patterns have been enabled.
-
-p. Before enabling them, ensure you are familiar with identifiers with extensions. See %ref[item=/doc/identifiers-and-patterns.*,frag=identifiers]{} section for documentation.
-
-p. To use identifiers with extensions:
-
-ol[spacious].
-  li. Set %code{identifier_type} to %code{full} in the configuration file. For example:
-
-    listing[lang=yaml,legacy].
-      identifier_type: legacy
-
-    listing[lang=yaml,new].
-      identifier_type: full
-
-  li. Remove the trailing slash from any argument to %code{#compile}, %code{#route} and %code{#layout} in the %filename{Rules} file, as well as in calls to %code{@items[…]}, %code{@layouts[…]}, and %code{#render} throughout the site. If the pattern does not end with a “%code{*}”, add “%code{.*}”. For example:
-
-    listing[lang=ruby,legacy].
-      compile '/articles/**/*/' do
-        filter :kramdown
-        layout '/default/'
-      end
-
-      compile '/about/' do
-        layout '/default/'
-      end
-
-    listing[lang=ruby,new].
-      compile '/articles/**/*' do
-        filter :kramdown
-        layout '/default.*'
-      end
-
-      compile '/about.*' do
-        layout '/default.*'
-      end
-
-    listing[lang=ruby,legacy].
-      @items['/about/']
-      @layouts['/default/']
-
-    listing[lang=ruby,new].
-      @items['/about.*']
-      @layouts['/default.*']
-
-    listing[lang=rhtml,legacy].
-      <%%= render '/root/' %%>
-
-    listing[lang=rhtml,new].
-      <%%= render '/root.*' %%>
-
-  li. Update the routing rules to output the correct path. For example:
-
-    listing[lang=ruby,legacy].
-      route '/articles/*/' do
-        # /articles/foo/ gets written to /articles/foo/index.html
-        item.identifier + 'index.html'
-      end
-
-    listing[lang=ruby,new].
-      route '/articles/**/*' do
-        # /articles/foo.md gets written to /articles/foo/index.html
-        item.identifier.without_ext + '/index.html'
-      end
-
-  li. Create a routing rule that matches index files in the content directory (such as %filename{content/index.md} or %filename{content/blog/index.md}). For example, put the following _before_ any rules matching %code{/**/*}:
-
-    listing[lang=ruby,new].
-      route '/**/index.*' do
-        # /projects/index.md gets written to /projects/index.html
-        item.identifier.without_ext + '.html'
-      end
-
-  li. Replace calls to %code{#children} with a call to %code{#find_all}, passing a pattern that matches the children. For example:
-
-    listing[lang=ruby,legacy].
-      @items['/articles/'].children
-      @item.children
-
-    listing[lang=ruby,new].
-      @items.find_all('/articles/*')
-      @items.find_all(@item.identifier.without_ext + '/*')
-
-  li. Replace calls to %code{#parent} with a call to %code{#[]}, passing a pattern that matches the parent. For example:
-
-    listing[lang=ruby,legacy].
-      @item.parent
-
-    listing[lang=ruby,new].
-      @items[@item.identifier.to_s.sub(/[^\/]+$/, '').chop + '.*']
-
-note. When using identifiers with extensions, the children and parent of an item are no longer unambiguous. For example, the two items %filename{/foo.md} and %filename{/foo.adoc} both have %filename{/foo/bar.md} as a child, and %filename{/foo/bar.md} has two parents.
-
-h3. Upgrading from the static data source
-
-note. This section assumes that glob patterns and identifiers with extensions have been enabled.
-
-p. The static data source no longer exists in Nanoc 4. It existed in Nanoc 3 to work around the problem of identifiers not including the file extension, which is no longer the case in Nanoc 4.
-
-p. Theoretically, with identifiers with extensions enabled, it is possible to move the contents of the %filename{static/} directory into %filename{content/}. This can be tricky, however, because some rules that did not match any items in %filename{static/} might now match.
-
-p. Because of this, the recommend approach for upgrading is to keep the %filename{static/} directory, and set up a new data source that reads from this directory.
-
-p. In the site configuration, re-enable the static data source, change its type to %code{filesystem}, set %code{content_dir} to %code{"static"} and %code{layouts_dir} to %code{null}:
-
-listing[lang=yaml,new].
-  data_sources:
-    -
-      type: filesystem
-    -
-      type: filesystem
-      items_root: /static
-      content_dir: 'static'
-      layouts_dir: null
-
-p. The null value for the %code{layouts_dir} option prevents this data source from loading layouts—the other data source already does so.
-
-p. Lastly, update the rules to copy these items as-is, but without the %code{/static} prefix:
-
-listing[lang=ruby,new].
-  compile '/static/**/*' do
-  end
-
-  route '/static/**/*' do
-    # /static/foo.html → /foo.html
-    item.identifier.to_s.sub(/\A\/static/, '')
-  end
-
-p. This approach should work out of the box: Nanoc should not raise errors and the output diff should be empty.
-
-p. A final improvement would be to move the contents of the %filename{static/} directory into %filename{content/}. The main thing to watch out for with this approach is rules that accidentally match the wrong items.
-
-h2. Troubleshooting
-
-ol[spacious].
-  li. If you use Nanoc with a Gemfile, ensure you call Nanoc as %kbd{bundle exec nanoc}. Nanoc no longer attempts to load the Gemfile.
-
-  li. If you get a %code{NoMethodError} error on %code{Nanoc::Identifier}, call %code{.to_s} on the identifier before doing anything with it. In Nanoc 4.x, identifiers have their own class and are no longer strings.
-
-  listing[lang=ruby,legacy].
-    item.identifier[7..-2]
-
-  listing[lang=ruby,new].
-    item.identifier.to_s[7..-2]
-
-  li. If you get a %code{NoMethodError} that you did not expect, you might be using a private API that is no longer present in Nanoc 4.0. In case of doubt, ask for help on the %ref[url=http://nanoc.ws/community/#discussion-groups]{discussion group}.
-
-h2. Removed features
-
-p. The %code{watch} and %code{autocompile} commands have been removed. Both were deprecated in Nanoc 3.6. Use %ref[url=https://github.com/guard/guard-nanoc]{%productname{guard-nanoc}} instead.
-
-p. Because Nanoc’s focus is now more clearly on compiling content rather than managing it, the following features have been removed:
-
-ol.
-  li. the %code{create-item} and %code{create-layout} commands
-  li. the %code{update} and %code{sync} commands
-  li. VCS integration (along with %code{Nanoc::Extra::VCS})
-  li. the %code{DataSource#create_item} and %code{DataSource#create_layout} methods.