Nanoc»Identifiers and patterns

In Nanoc, every item (page or asset) and every layout has a unique identifier: a string derived from the file’s path. A pattern is an expression that is used to select items or layouts based on their identifier.

Identifiers

Identifiers come in two types: the full type, new in Nanoc 4, and the legacy type, used in Nanoc 3.

full
An identifier with the full type is the filename, with the path to the content directory removed. For example, the file /Users/denis/stoneship/content/about.md will have the full identifier /about.md.
legacy
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 /Users/denis/stoneship/content/about.md will have the legacy identifier /about/. This corresponds closely with paths in clean URLs.

The following methods are useful for full identifiers:

identifier.without_extString
identifier with the last extension removed
identifier.without_extsString
identifier with all extensions removed
identifier.extString
the last extension of this identifier
identifier.extsString
all extensions of this identifier
identifier + stringString
identifier with the given string appended

Here are some examples:

identifier = Nanoc::Identifier.new('/about.md')

identifier.without_ext
# => "/about"

identifier.ext
# => "md"

The following method is useful for legacy identifiers:

identifier.chopString
identifier with the last character removed

Here are some examples:

identifier = Nanoc::Identifier.new('/about/', type: :legacy)

identifier.chop
# => "/about"

identifier.chop + '.html'
# => "/about.html"

identifier + 'index.html'
# => "/about/index.html"

Patterns

Patterns are used to find items and layouts based on their identifier. They come in three varieties:

  • glob patterns
  • regular expression patterns
  • legacy patterns

Glob patterns

Glob patterns are strings that contain wildcard characters. Wildcard characters are characters that can be substituted for other characters in an identifier. An example of a glob pattern is /projects/*.md, which matches all files with a md extension in the /projects directory.

Globs are commonplace in Unix-like environments. For example, the Unix command for listing all files with the md extension in the current directory is ls *.md. In this example, the argument to the ls command is a wildcard.

Nanoc supports the following wildcards in glob patterns:

*
Matches any file or directory name. Does not cross directory boundaries. For example, /projects/*.md matches /projects/nanoc.md, but not /projects/cri.adoc nor /projects/nanoc/about.md.
**/
Matches zero or more levels of nested directories. For example, /projects/**/*.md matches both /projects/nanoc.md and /projects/nanoc/history.md.
?
Matches a single character.
[abc]
Matches any single character in the set. For example, /people/[kt]im.md matches only /people/kim.md and /people/tim.md.
{foo,bar}
Matches either string in the comma-separated list. More than two strings are possible. For example, /c{at,ub,ount}s.txt matches /cats.txt, /cubs.txt, and /counts.txt, but not /cabs.txt.

A glob pattern that matches every item is /**/*. A glob pattern that matches every item/layout with the extension md is /**/*.md.

Regular expression patterns

You can use a regular expression to select items and layouts.

For matching identifiers, the %r{…} syntax is (arguably) nicer than the /…/ syntax. The latter is not a good fit for identifiers (or filenames), because all slashes need to be escaped. The \A and \z anchors are also useful to make sure the entire identifier is matched.

An example of a regular expression pattern is %r{\A/projects/(cri|nanoc)\.md\z}, which matches both /projects/nanoc.md and /projects/cri.md.

Legacy patterns

Legacy patterns are strings that contain wildcard characters. The wildcard characters behave differently than the glob wildcard characters.

To enable legacy patterns, set string_pattern_type to "legacy" in the configuration. For example:

string_pattern_type: "legacy"

For legacy patterns, Nanoc supports the following wildcards:

*
Matches zero or more characters, including a slash. For example, /projects/*/ matches /projects/nanoc/ and /projects/nanoc/about/, but not /projects/.
+
Matches one or more characters, including a slash. For example, /projects/+ matches /projects/nanoc/ and /projects/nanoc/about/, but not /projects/.