Project internals

.nift/tracked.json.

tracked.json is the compact list of files/pages Nift is managing. Each tracked entry gives Nift a stable name and title. A template is optional: templated entries compose content through a template, while template-less entries parse their content file directly as the top-level Nift source. Project-wide path rules come from config.json.

A small example

{
  "tracked": [
    {
      "name": "/",
      "title": "Home",
      "template": "templates/template.html"
    },
    {
      "name": "about",
      "title": "About us",
      "template": "templates/template.html"
    },
    {
      "name": "docs/getting-started",
      "title": "Getting started",
      "template": "templates/docs.html"
    }
  ]
}

Required fields

Template-less tracked entries

Not every tracked output needs a wrapper template. Omit template when the content file itself should be the complete parsed Nift source:

{
  "name": "assets/app",
  "title": "Application JavaScript",
  "content-ext": ".js",
  "output-ext": ".js"
}

For a template-less entry, Nift parses the derived content file directly, so Nift syntax inside that file still works. There is simply no outer template and therefore no template dependency. This is useful for tracked CSS, JavaScript, XML, feeds and other generated text where an identity template would add ceremony without adding structure.

Nift's default scaffold uses this form for its tracked CSS and JavaScript assets rather than creating identity templates such as template.css or template.js.

Optional per-item extensions

An entry can override the project's default content or output extension:

{
  "name": "feed",
  "title": "Feed",
  "template": "templates/feed.xml",
  "content-ext": ".xml",
  "output-ext": ".xml"
}

The v4 reader recognises content-ext, output-ext and the optional boolean minify override on individual tracked entries. If they are absent, the defaults in .nift/config.json are used.

Optional per-item minification

A tracked entry may override the project-wide minify-exts decision:

{
  "name": "assets/app",
  "title": "App",
  "template": "templates/app.js",
  "content-ext": ".js",
  "output-ext": ".js",
  "minify": true
}

true forces minification, false disables it, and an omitted field inherits the project's extension-based setting. The field must be a JSON boolean. Read the minification guide →

Optional pagination

A tracked item can own a generated pagination set:

{
  "name": "blog",
  "title": "Blog",
  "template": "templates/template.html",
  "paginate": {
    "items-per-page": 10,
    "template": "templates/pagination/posts.html",
    "separator": "templates/pagination/post-separator.html"
  }
}

items-per-page is required and must be a positive integer. template and separator are optional paths: without an explicit template Nift uses the required conventional <content-stem>.paginate.html; without an explicit separator it uses <content-stem>.separator.html when present, otherwise no separator is inserted.

The entire generated page set remains one tracked item for invalidation and failure semantics. Read the pagination guide →

Names are the useful abstraction

Suppose your config uses content/, public/ and .html. This entry:

{
  "name": "blog/hello-world",
  "title": "Hello world",
  "template": "templates/post.html"
}

corresponds to:

tracked name:   blog/hello-world
content path:   content/blog/hello-world.html
template path:  templates/post.html
output path:    public/blog/hello-world.html

Usually manage it through Nift

nift track about "About us" templates/template.html
nift mv about company
nift cp company team
nift untrack old-page
nift rm obsolete-page

Those commands update Nift's tracking information for you. Because the file is ordinary JSON, it is still easy to inspect, version-control and understand when debugging a project.

Validation Nift performs while loading

The current v4 reader requires a top-level tracked array, requires every item to have string name and title values, requires template to be a string when present, validates optional pagination metadata and positive integer items-per-page, rejects duplicate tracked names, and rejects an item whose derived content path is the same as its template path.