Contents

In Punch, content for a page should be defined as a JSON object. These content objects must be saved as .json files in the contents directory to form the site structure.

A content object can be composed of standard JSON data types such as strings, numbers, booleans, arrays and objects.

Here's how a sample content object for a page would look like:

{
	"title": "About Us",
	"banner_img": "/img/team_pic.png",
	"intro": "We are the most awesome company in the world.",
	"team": [
		{
			"name": "Pointy-headed Boss",
			"title": "CEO",
			"profile_pic": "/img/boss.png",
			"profile": "He's the World's Best Boss."
		},
		//snip
	]
}

In layouts, you can use the property names to call the values defined in a content object.

Here's how we would define the layout to render the above content object.

<!--snip-->
<h2>{{title}}</h2>
<div>
	<img src="{{banner_img}}">
	<p>{{{intro}}}</p>
</div>

<ul>
{{#team}
	<li>
		<h3>{{name}} - {{title}}</h3>
		<img src="{{profile_pic}}">
		<p>{{profile}</p>
	</li>
{{/team}
</ul>
<!--snip-->

Extended contents

While, JSON format works great for structured content, it would not be ideal to define long, formatted texts. Practically, properties such as intro from the above example, wouldn't be just a single sentence. It will span into multiple paragraphs and can contain hyperlinks, emphasizing, etc.

You can move such contents into their own files. These are known as extended contents. All extended contents for a page must be placed in a directory named by the page name preceded with an underscore (eg. _index, _about). Punch will merge all properties defined in a extended content directory into the regular content object.

Punch will actually try to parse the extended content files, before merging them into the regular content object. By default, Punch can parse content defined as Markdown. You can easily add your own parsers for other content types too.

Shared contents

There are some contents that needs to be available to all pages of the site. For example, every page will need to access the items for the navigation bar. You can define such globally accessible contents in the contents/shared.json. It can also have an extended contents directory by the name contents/_shared.

Write your own content handler

Though the default content handler of Punch works with the local file system, you can easily customize Punch to consume content from any data source that can output JSON. This could be a REST API, relational database like Postgre, a document store like MongoDB or a backend service like Firebase. Writing a Custom Content Handler section, will provide more details.