Content metadata

The metadata provide additional information for the content that are used to compose the web page. These data help to create menus, determine the layout of the web page, or optimize the search engines of the Internet. The metadata have to be at the beginning of the content file enclosed in HTML comment tags.

For example the metadata of this page looks like this:

<!-- ======================================================================
--- Search engine
title:          Content metadata
keywords:       content, metadata
description:    Content metadata in md-site-engine.
--- Menu system
order:          20
text:           Content metadata
hidden:         false
umbel:          false
--- Page properties
id:             
document:       
layout:         layout-2-left
$-left:         #side-menu
searchable:     true
rewrite:        
--- Side menu
side-menu-root:     /documentation
side-menu-header:   Documentation
side-menu-top:      Introduction
side-menu-depth:    2
======================================================================= -->

The lines containing the opening (<!--) and the closing (-->) of the HTML comment are ignored, just like the lines starting with three dashes (---). All other lines must be follow this format: propertyName : value. The engine uses those properties displayed in the example, however, the metadata can expanded by any user defined properties to use in custom controls and actions.

Search engine properties

These properties are used to provide metadata for the HTML document, and are typically used by search engines of the Internet.

title

Type: string Default value: ''

The value of the <title> tag in the header of the HTML document, i.e. the title of the web page.

keywords

Type: string Default value: ''

The value of the <meta> tag named keywords in the header of the HTML document. It is used to describe the content of the web page by enumerating the most specific phrases.

description

Type: string Default value: ''

The value of the <meta> tag named description in the header of the HTML document. It is used to describe the content of the web page by a short sentence.

The engine builds an object tree based on the content files and the structure of the contents directory. The particular objects can be extended by these properties. The engine uses this object tree to generate menus when renders pages. There are two predefined controls for that purpose: bootstrap-navbar and side-menu. For more information see the Menu system.

order

Type: number Default value: undefined

The order of the menu item in a menu. When not set, no menu item is generated for the content.

text

Type: string Default value: ''

The text of the menu item in a menu. Use cases:

Value Result
(empty) the default menu text is '-?-'
--- a menu separation item is generated
@text a menu text is generated without link to a content
any other string a menu item is generated for the content

hidden

Type: Boolean Default value: false

When the value is true, no menu item is generated - even if the text property has value.

umbel

Type: Boolean Default value: false

When the value is true, the menu item is counted active if the beginning of the path of the current page equals to the path of the menu item. In other words this menu item is an umbrella for those sub-pages that are not shown in the menu.

Page properties

The page properties help to customize the layout and/or the content fragments of the web page.

id

Type: string Default value: '<path>'

The identifier of the content, it defaults to the path of the content file. In the language directories the same content files can have different names, so they will have different paths. If you want to joint these files you have to set the identifiers of the matching contents to the same value. A practical solution is to use the path of the content file in the default language. In that case when the user changes language he or she lands on the same web page localized in the selected language.

document

Type: string Default value: ''

The name of document segment that the engine uses to render the web page. When it is not set, the engine uses the default document set in the configuration.

layout

Type: string Default value: ''

The name of layout segment that the engine uses to render the web page. When it is not set, the engine uses the default layout set in the configuration.

segment-<name> --or-- $-<name>

Type: string Default value: ''

The segment with the indicated name should be replaced by the segment set in the value. This can be useful for example to alternate the contents of segments defined by the layout files.

searchable

Type: Boolean Default value: true

When the value is false, the content search skips the given content.

rewrite

Type: string Default value: ''

When the rewrite property is defined, the engine makes an inner URL rewrite using the value of the property. The value has to be the path of a content file, and the web page will display that content.

Side menu properties

These properties are used by the side-menu control. For details see the Menu system.

side-menu-root

Type: string Default value: '' Required.

The path of the object in the menu tree which child items will be in the menu of. For that reason the object has to be a menu node.

side-menu-header

Type: string Default value: ''

The locale key of an optional title for the side menu. If the locale is not found, the value will be the title.

side-menu-top

Type: string Default value: ''

When defined, the root menu will be added as the first item to the side menu. The value is the locale key of the text of the menu item. If the locale is not found, the value will be the menu text.

side-menu-depth

Type: number Default value: 1

The number of the levels in the menu tree that are used to generate the side menu.