DOCSEARCHbyAlgolia
Submit Docs

Nanoc Static Site Generator

website·Indexed 35 days ago

https://nanoc.app/about/

A flexible static-site generator (SSG) for building everything from personal blogs to corporate websites. Documentation covers installation via RubyGems, site structure, data sources, filters, helpers, and deployment. Includes technical references for the nanoc CLI, compilation rules, and upgrade guides for Nanoc 4.

Tokens
31.6K
Snippets
215
Records
310
Agent score
70%

What's inside Nanoc

  1. Overview of Nanoc Rules

    The Rules file contains processing instructions for all items in a Nanoc site. Nanoc uses the first matching rule found in the file for any given item or layout. There are three primary types of rules:

    1. Compilation rules: Define actions like filtering, layouting, and snapshotting.
    2. Routing rules: Define the output path where compiled items are written.
    3. Layouting rules: Define which filter should be used for a specific layout.

  2. Overview of Nanoc static-site generator

    Nanoc is a flexible, command-line static-site generator (SSG) used to transform content from formats like Markdown or AsciiDoc into HTML. Unlike a CMS, Nanoc does not manage content; it processes files from the file system. Because Nanoc is a programmable tool, a basic understanding of Ruby is recommended for users.

  3. Understand Nanoc Identifiers

    In Nanoc, every item (page or asset) and every layout has a unique identifier derived from the file's path. There are two types of identifiers:

    1. Full (Nanoc 4+): The filename with the content directory path removed. Example: /Users/denis/stoneship/content/about.md becomes /about.md.
    2. Legacy (Nanoc 3): The filename with the content directory path and extension removed, with a trailing slash appended. Example: /Users/denis/stoneship/content/about.md becomes /about/.

  4. Access Nanoc site variables

    Nanoc exposes site data through variables prefixed with the @ sigil (e.g., @items). These variables are available in preprocess/postprocess blocks, compile and route rules, and during filtering/layouting. In some filters, the @ sigil may need to be dropped (e.g., using items instead of @items).

  5. Resolve AmbiguousMetadataAssociation error

    This error occurs when multiple content files share the same basename (e.g., about.md and about.txt) and there is a corresponding metadata file (e.g., about.yaml), leaving Nanoc unable to determine which content file the metadata belongs to.

    Nanoc will only avoid this error if exactly one of the content files lacks inline metadata (frontmatter). The recommended solution is to give each content file a unique name.

  6. Use the show-data and show-plugins commands to inspect site state

    In nanoc version 3.4, the debug and info commands were renamed to show-data and show-plugins, respectively. The show-data command provides information about items, reps, and layouts, and was further improved in version 3.4.2 to show more accurate dependencies.

  7. Use the current item representation with @item_rep or @rep

    The @item_rep (or alias @rep) variable provides details about the item representation currently being processed during filtering and layouting.
    @item_rep.name # e.g., :default
@item_rep.item # The associated item
@item_rep.path(snapshot: :foo) # Path to compiled rep
@item_rep.raw_path(snapshot: :foo) # Raw path
@item_rep.binary? # Check if :last snapshot is binary

  8. Handle binary items in Nanoc

    Nanoc supports binary items (such as images, fonts, audio files, and videos). Unlike textual items, binary items are not loaded into memory, allowing Nanoc to handle large files efficiently. To ensure binary files are copied to the output directory without being processed by filters, use the passthrough rule in the Rules file.
    passthrough '/gallery/*'

  9. Understand Nanoc's Entity and View data model

    Nanoc divides data into two categories: Entities and Views.

    • Entities: Contain the actual data. Examples include Item, Layout, Document, and ItemRep. These are located in lib/nanoc/base/entities.
    • Views: Wrap entities to provide context-specific APIs. Examples include MutableItemView (used during preprocessing to allow mutation), CompilationItemView, and PostCompileItemView (provides modified_reps()). These are located in lib/nanoc/base/views.

    Converting a view back to an entity is done via the private _unwrap() method, though this is not intended for use outside the Nanoc codebase.

  10. Understand Nanoc Items and Representations

    In Nanoc, an 'item' refers to any page (e.g., an about page) or asset (e.g., a stylesheet or image). Each item consists of content, an identifier, and free-form metadata attributes (key-value pairs).

    Items are categorized as textual or binary based on the text_extension list in the site configuration. Binary items are not stored in-memory; instead, they maintain a filename pointer to the content.

    Every item has one or more 'representations' (reps), which are the compiled forms of the item (e.g., html, json, rss). Unless specified otherwise, there is a default representation named default.

  11. Compile SCSS files to CSS in Nanoc

    To use the SCSS syntax instead of the default Sass syntax, match .scss files and pass the syntax: :scss option to the :sass filter.
    compile '/**/*.scss' do
  filter :sass, syntax: :scss
  write @item.identifier.without_ext + '.css'
end