Format

Contents

  1. Introduction
  2. Meta blocks
  3. Declarations

Introduction

The Cyblog format is intended to be fully compatible with existing Markdown implementations (specifically, GitHub-flavoured Markdown), and adds a few extra features to make Markdown suitable as a language for static site generation.

This means bold, italics, lists, headers, links, tables, and images, along with other standard markdown syntax, are all supported out-of-the-box.

Cyblog will also be able to parse standard .md files, although it will not look for or consider cyblog metadata present in those files.

In the future, Cyblog might add support for footnotes, but this is not a goal for the first release.

Additionally, Cyblog's first release will not apply syntax highlighting to code blocks, or automatically convert links that don't use the link syntax.

Meta blocks

Introduction

Cyblog extends Markdown through meta blocks, which are comments that follow a specific format designed to be convenient to parse and human-readable.

Syntax

Every Cyblog document must contain at least the following meta block at the beginning of the file:

<!-- cyblog-meta
@title Document Title
-->

The first line of the comment indicates to Cyblog that this is a meta block. The first line of every meta block must follow the format:

<!--<SPACE>cyblog-meta<NEWLINE>

Where SPACE is a single space character.

Additionally, the closing --> of a meta block must appear on a line by itself, with no other whitespace.

Meta blocks can appear anywhere in a document, but the first one is special - Cyblog looks at it to determine the title of your page. This first meta block is called the document meta block.

Each line in a Cyblog meta block is known as a declaration.

Declarations must adhere to the following format:

@<DECLARATION NAME><WHITESPACE><DECLARATION VALUE><NEWLINE>

where <WHITESPACE> is either a number of SPACE characters or a single Tab character.

The rest of the line is considered the value for that declaration. Declaration names must match the following regex:

[a-z][a-z\-]+[a-z]

Which is to say, they must be atleast three characters long, begin and end with a lowercase letter, and contain only lowercase letters and hyphens. Declaration values may, of course, contain any characters in any format, but they may not contain newlines.

If Cyblog does not understand a declaration, a warning is generated.

Single-line declaration syntax

For convenience reasons, Cyblog has a special syntax for meta blocks that only contain a single declaration.

<!--<SPACE>@<DECLARATION NAME><WHITESPACE><VALUE><SPACE>-->

Note: Due to the nature of the parser used in Cyblog, declarations must be preceded and followed by blank lines.

Declarations

Document declarations

apply-style

Note: Cyblog DOES NOT perform any linting of CSS files.

template

Note that template types are NOT final yet.

Metadata blocks

(html-meta and meta-*)

Metadata declarations are parsed dynamically, so you can store and set whatever values you see fit.

Block declarations

A block is a Cyblog object that gets translated to a div.

include

Note: Cyblog DOES NOT perform any linting of @included HTML snippets.

block-start
block-end
Parenting