Configuration Options

You can tweak almost any aspect of Punch's default behaviour from configurations. By default, the main configuration file for the project is named config.json and it's stored in the top-level directory of the project.

Organizing Configurations

If you feel maintaining all configurations within a single file is getting cumbersome, you can split configurations for each section into its own file and store them all in a directory named config.

Since, most Punch commands accepts a configuration path explicitly, you can have multiple configurations for same project and provide the appropriate one during the run-time (imagine using different configurations for development, staging and live environments).

Take a look at the default configuration used by Punch. You can override or extend any of the properties defined here.

Defining Configurations

When you define a primitive-value (string, integer and boolean) property, it will override the default value specified for it. However, properties having Object and Array literals as the values will be extended with the properties you define.

Let's try to understand this from an example:

	{
		"template_dir": "custom_templates",

		"plugins": {
			"parsers": {
				".txt": "text_parser.js" 
			}
		}
	}

The above configuration will override project's default template_dir with the given template path. But the definition of parsers will extend the list of existing parsers with the new one. It means now the project have both Markdown and Text parsers.

If you want to force Punch to override the default value, you have to append the term Override to the property name.

	{
		"plugins": {
			"parsersOverride": {
				".txt": "text_parser.js" 
			}
		}
	}

This will override the default parsers list with the one you defined, making Text, the only available parser.

All available configuration options

template_dir - Path of the template directory (default: templates)

content_dir - Path of the contents directory (default: contents)

output_dir - Path of the output directory, where rendered files will be stored. (default: public)

shared_content - Name of the file or extended directory where shared content is stored. (default: shared)

asset_bundling

• skip_hosts - Hosts to exempt from asset bundling. Usualy these are the localhosts. (default: ["localhost", "127.0.0.1", ".local"])

• fingerprint - When set to true, a timestamp based fingerprint will be appended to bundle file's name. Useful for easy cache busting in CDN based setups (default: false)

bundles - Specify available asset bundles. Check the section Minfify-and-Bundle-Assets for more details.

generator

• blank - When set to true, site generator will remove any existing files and start generation from a blank state. (default: false)

• skip_paths - Specify paths to skip from generating as an array. Path values can contain regular expressions (eg. "/assets/less*")

parser

• markdown - You can pass an options object to Markdown parser. This could be any valid option supported by Marked.

	"parser": {
		"markdown": {
			"gfm": true,
			"pedantic": false,
			"sanitize": true
		}
	}

publish

• generate - When set to true, site will be generated before publishing. (default: true)

plugins - All plugin paths should be valid node.js require paths. Start a paths name with ("./") to specify the path relative to the current project path.

Refer relavant sections under Punch Object Model to learn how to write a plugin to override or extend the default behaviour.

server

• port - Port to listen for requests (default: 9009)

• cache

  -- max_age - Maximum time to cache a request (in seconds) (default: 0),

  -- directives - Cache control directives to set (default: ["public"], available: ["public", "private", "no-cache", "no-store", "no-transform", "must-revalidate", "proxy-revalidate"])