Format

Introduction
Meta blocks

title

Declarations

Document declarations
apply-style
template
Metadata declarations
Block 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.

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`

To apply a certain stylesheet to a document, add the apply-style declaration to the document meta block. The value of this declaration must be a path (either relative or absolute) to a CSS file. You can have as many apply-style declarations as you like.
```

```
To apply a builtin style, use the @builtin-<name> syntax. Builtin styles are styles that ship with Cyblog and don't require the .css extension while they're being applied.
```

```
Available builtin styles:
- dark - A dark mode for your site.
- mediaquery-dark - Uses a media query to apply dark theming only for users that want it.

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

`template`

To apply a specific style from Cyblog's list of built-in styles, use the template declaration in the document meta block.
```

```

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.

To add a meta tag to the head of the generated HTML document, add a html-meta declaration to the document meta block. The declaration value must be a comma-separated list of attribute-value pairs joined by colons. An example is given below.

For example:
```

```
gets transformed into:
```
<meta name="author" content="John Doe">
<meta name="description" content="John Doe's Cyblog">
```

meta-* declarations are are parsed dynamically and if they have the display:true directive they are turned into span elements with the class .cyb-meta-* applied to them, so you can style them as you like.

They are placed below the first heading found in the document.

The block

<!-- cyblog-meta
@title John Doe's Page
@meta-author display:true John Doe
@meta-tags display:true abc,def,ghi
@meta-category display:true abc,def,ghi
@meta-internal display:false hiddenvalue
-->

# Welcome to my page!

gets transformed into the following:

(Contents unrelated to meta-* declarations may change in the future)

<!DOCTYPE html>
<html>
  <head>
    <title>John Doe's Page</title>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel='stylesheet' href='style.css'>
  </head>
  <body>
    <h1 class='cyb-h1' id='welcome-to-my-page'> Welcome to my page! </h1>
    <span class='cyblog-meta-author'> John Doe </span>
    <span class='cyblog-meta-tags'> abc,def,ghi </span>
    <span class='cyblog-meta-category'> abc,def,ghi </span>
  </body>
</html>

Block declarations

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

`include`

To add a common block (such as a nav or a footer) to a document, use the include declaration. The value of this declaration must be a path to a plaintext file containing an HTML snippet. The file's contents will be added to the document in the correct place before it is processed, in a manner similar to copy-pasting.
```

```

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

`block-start`

To mark a text block as a special block so you can apply styling to it, add a meta block before it, with the declaration block-start, with the value being an identifier for that block.

Block names must follow the same constraints as declaration names, and must additionally be unique.

For example:
```

```
block-start declarations are also used to apply ids and classes to elements. This is done in the following way:
```

```
You can apply multiple classes, too.
```

```
Blocks also enable Cyblog's templating features: if you have template:true in the block-start declaration, Cyblog will perform mustache replacement on the block contents using the document meta block's meta-* declarations.

You can escape mustaches by prefixing them with double backslashes.
```


{{ foo }}
\\{{ baz }}

```
Is rendered to:
```
  <div class='templated-block'>
  bar
  {{ baz }}
  </div>
```
See demo.cyblog for more examples.

`block-end`

To close a block, simply add a meta block with the block-end declaration.

Blocks with this declaration must only contain that declaration and nothing else.
```

```

Parenting

Every standard Markdown construct between ablock-start and a block-end declaration will be treated as a child of the block those declarations enclose.