Documentation

Function Reference

get_part(part)

Provides a shortcut to include a file named {part}.php that resides in common/ folder.

The function uses require so you may include the same part multiple times.

Example

// Include 'header.php' located in common folder
<?php get_part('header') ?>

// Include 'footer.php' located in common folder
<?php get_part('footer') ?>

get_title(false|true)

Returns the page['title'] value stored in page.json or a string extracted from the page folder name.

In the latter case if true is passed the title is formatted with ucwords();

get_content(block)

Read a Markdown content block from file {block}.md, default to main.md.

If a block-specific {block}.css is found than it's automagically included.

Example

<main>
    // Read and parse 'main.md' file content
    <?php echo get_content() ?>
</main>

<aside>
    // Read and parse 'related.md' file content
    <?php echo get_content('related') ?>
</aside>

// Output
<main>
    // Read and parse 'main.md' file content
    <h1>This is the main content title</h1>
    <p>This content is stored in the main.md file.</p>
    <p>No main.css file was provided so no CSS was printed.</p>
</main>

<aside>
    // Read and parse 'related.md' file content
    <h2>This is the related content title</h2>
    <p>This content is stored in the related.md file.</p>

    //The related.css file was found, its content was printed after the block.
    <style media="screen">
        h2 {
            color: #733;
            border-left: 1em solid #733;
        }
    </style>
</aside>

get_navigation(name, format)

Retrieve the name navigation array from $page['navs'] and return a list of links, default to main. Format argument accepts the following values for list-formatting:

• ol for ordered-list of links
• ul for unordered-list of links
• nav (default) for nav tag containing linked span elements

Each list tag is assigned two classes: menu-{$name} and menu-{$type}, please refer to page.json section for type definition. A current class is added if the list slug is the same as the page slug.

Files Reference

Every folder represents a single page, it has its own URL and it's made-up by a few files and one folder.

index.php

The PHP file where the page template is composed by its parts. It can be completely customized or copied/pasted from your pre-composed template file. Obviously it's a required file.

main.md

The page's main content file, where body text it's written and formatted using Markdown. It's not strictly required – you can place your HTML content directly in index.php – but consider the importance of keeping your content and logic separated.

page.json

In this file you can add some metadata and navigations related to your page, available in the $page global variable for your convenience.

The JSON is structured in two main objects:

page object

Here you can provide metadata (title, description, content datetime…) Kowari provides a basic empty template and the minimal logic for printing <meta> tags and JSON-LD object out of the file content. Page metadata array is merged with meta.json where common and generic websites info are provided.

You can edit the file by filling the value fields, but do not edit the keys. It's not required, but useful for SEO and social media.

navs object

You can define multiple menus by choosing a name, a type and provide a list of navigation elements, see the example below.

"navs": {
    "main-toc": {
        "type": "toc",
        "items": [
            {
                "label": "Introduction",
                "slug": "introduction"
            },
            {
                "label": "Main Features",
                "slug": "main-features"
            },
            {
                "label": "Pricing",
                "slug": "pricing"
            }
        ]
    },

    "footer": {
        "type": "flat",
        "items": [
            {
                "label": "Company Profile",
                "slug": "company-profile"
            },
            {
                "label": "Contact Us",
                "url": "mailto:info@example.com"
            },
            {
                "label": "Parent Holding Website",
                "url": "https://www.holding.com/",
                "blank": true
            }
        ]
    }
}

Menus Attributes

• name can be any string suitable as HTML5 CSS class name, must be unique, default to main
• type can be one of the following:
  • flat identify a non-hierarchical group of link
  • toc for Table of Contents nav menus, use slugs for anchor links

Items Attributes

• label can be any string (required)
• slug can be any slug that will be used for URL composition, overriden by url if present
• url can be any URL, overrides slug
• blank can be false (default) or true, open the link in a new window or equivalent

JSON

If you are novice with JSON please consider to validate your code with JSON Formatter.

media/

Each page can have its own media folder, where you can upload the images you use in your content.

The breakpoint name defined is used as a suffix in image file name to identify specific formats, please pay attention to the double dash --.

Refer to Using Picture Tag in Markdown for Markdown syntax.

Example:

// In your Markdown file
{boston; Hello World!; cover}

// In your HTML
<picture class="cover">
    <source srcset="media/boston--mob.webp 2x" width="960" height="960" type="image/webp" media="(max-width: 480px)">
    <source srcset="media/boston--tab.webp 2x" width="1600" height="1200" type="image/webp" media="(max-width: 960px)">
    <source srcset="media/boston--dsk.webp 2x" width="1920" height="1280" type="image/webp" media="(max-width: 1280px)">
    <img src="media/boston.jpg" alt="Hello World">
</picture>

Insights

Using Picture Tag in Markdown

A Markdown/Parsedown extension has been developed to output the appropriate <picture> tag and related <source>, so it's possible to propose a set of images optimized for every viewport in terms of format, proportion and size.

If you are new to art-direction, picture element and sources please read Picture Element on MDN.

A BREAKS constant is defined in the custom config.php file of your site, here the names of the breakpoints and their limit sizes are listed.

// In your config.php
define('BREAKS', array(
    'mob' => 480,
    'tab' => 960,
    'dsk' => 1280,
    'base' => 1920
));

You can produce your set of image variations: each breakpoint can have his image proportion, for example 1:1 for mobile device and 16:9 for desktop.

Then you export the pictures in WEBP, JPG or PNG at resolution 2x breakpoint width and upload them in you page media/ folder. Consider optimizing the pictures before uploading for better download performance.

Each file must have the corresponding suffix, except for the defaul image (for older browser).

// In your media/ folder
boston--dsk.webp
boston--mob.webp
boston--tab.webp
boston.jpg