1. Manuals
  2. Tumbleweed
  3. blogc
  4. blogc-source(7)

Scroll to navigation

BLOGC-SOURCE(7) blogc Manual BLOGC-SOURCE(7)

NAME

blogc-source - blogc´s source file format

DESCRIPTION

Source files are used as input data to the blogc(1) compiler. They provide variables and content, that are used by the compiler to fill the gaps available in the templates (see blogc-template(7)).

The syntax of the source files is designed to be as simple as possible. The variables are defined in the top of the file as key-value lines, and the content is defined right after the variables.

Content is written in a markup language that is similar to John Gruber´s Markdown, but that is NOT Markdown. This language is very simple, while powerful enough to write big posts.

Content must be valid UTF-8.

SOURCE VARIABLES

Variables are key-value lines. The variable name must be upper-case, starting with a letter and following with one or more letters and/or underscores. The value is separated from the variable name with a ´:´ and finishes in the end of the line. Multi-line values are not supported.

VARIABLE1: Value of variable one
VARIABLE2: Value of variable two
--------------------------------

All the variables defined in the source files are local and will override global variables provided to blogc(1) in the command-line, but just inside blocks that handle local variables. See blogc-template(7) for details.

The DATE variable is special, and represents the publishing date of the post. It may be formatted with the DATE_FORMAT variable, if provided, otherwise will be kept as is. The proper way to access the date from the template is to use the DATE_FORMATTED variable, that will contain the formatted date, or the original date, depending on whether the DATE_FORMAT variable is provided or not.

The DATE variable should be in the following format: yyyy-mm-dd hh:mm:ss. You can omit seconds, minutes and hours if you want, they will be filled with ´0´. Allowed formats are yyyy-mm-dd hh:mm:ss, yyyy-mm-dd hh:mm, yyyy-mm-dd hh and yyyy-mm-dd

The DATE_FORMAT variable should be passed to blogc(1) as a global variable. Its value must be a valid strftime(3) format.

The source parser will also automatically generate a variable called FILENAME, that stores the name of the source file, without its extension. This is useful for building permalinks in templates. This variable can´t be overriden by an explicit definition in source file.

The variable FIRST_HEADER is created by the source parser by default, containing the unparsed value of the first header found in the source file. The content is not parsed but HTML entities are encoded. Headers inside blockquotes are ignored. This variable can be overriden by an explicit definition in source file, that must have the HTML entities escaped manually.

Another variable, DESCRIPTION, will be automatically created by the source parser. It contains the unparsed content of the first paragraph found in the source file. The content is not parsed but HTML entities are encoded. Paragraphs inside blockquotes are ignored. This variable can be overriden by an explicit definition in source file, that must have the HTML entities escaped manually. This is useful to add "description" meta-tags to HTML templates. It may be needed to truncate the variable size to an maximum length, take a look at blogc-template(7).

SOURCE CONTENT - BLOCK ELEMENTS

Paragraphs

Paragraphs are simple blocks of text.

This is a paragraph.
This is another paragraph.

Headers

Headers are defined starting with ´#´ characters, then number of characters is the level of the header.

# H1
## H2
### H3
#### H4

Each header will have an id attribute, that is a lowercase version of the unparsed header title, with non-alphanumeric characters replaced by ´-´. These ids can be used to create anchor links to specific sections of your content.

Blockquotes

Blockquotes are defined with lines starting with ´>´ characters. Content defined inside a blockquote is parsed again, so all the block elements are allowed inside blockquotes. The indentation after the ´>´ character must be preserved in the begin of each blockquote line.

> Hello,
>
> This is the blockquote example!

Unordered Lists

Unordered lists are defined with lines starting with ´*´, ´+´ or ´-´. The same starting character must be used for all the list items, and the indentation after the starting character must be preserved in the begin of each line.

* First item
* Second item
* Third item

Multi-line items are supported. Content must be aligned properly:

* First item


  Continuation of first item
* Second item
* Third item

Ordered Lists

Ordered lists are defined with lines starting with a number and a ´.´ character. The indentation after the starting character must be preserved in the begin of each line, meaning that the content of the items must be aligned. The order and value of the numbers is ignored.

1.  First item
2.  Second item
10. Tenth item

Multi-line items are supported. Content must be aligned properly:

1.  First item


    Continuation of first item
2.  Second item
10. Tenth item

To use numbers with ´.´ character in a non-list string, you must escape the ´.´.

1234\. This is not a list

Code Blocks

Code blocs are defined by indenting the lines with one or more whitespace characters.

This is a paragraph.


    This is a code block.


    Some more code.
This is another paragraph.

Horizontal Rules

Horizontal rules are defined as a paragraph with a sequence of 2 or more ´*´, ´+´ or ´-´ characters.

This is a paragraph before horizontal rule
***
This is a paragraph after horizontal rule

The horizontal rule must not be on its own paragraph, otherwise it will be parsed as a continuation of the previous paragraph.

HTML Blocks

HTML blocks are paragraphs started with ´<´ character. Everything is kept untouched in HTML blocks, until the next paragraph.

<p>This is raw HTML</p>
This is an usual paragraph
<p>This is more raw HTML</p>

Excerpt Separator

The excerpt is separated from the full content of a page/post using a paragraph with a sequence of 2 or more ´.´ characters.

After parsing, the excerpt will be part of the full content as well.

SOURCE CONTENT - INLINE ELEMENTS

Bold

Bold text is defined with 2 ´*´ or ´_´ before and after the text.

Bold text: **text**
Bold text: __text__

Italic

Italic text is defined with 1 ´*´ or ´_´ before and after the text.

Italic text: *text*
Italic text: _text_

Bold and Italic

Bold and italic text is defined mixing markers, like:

Italic and bold text: _**text**_
Italic and bold text: *__text__*
Italic and bold text: __*text*__
Italic and bold text: **_text_**

Code

Code is defined with 1 or 2 ´`´ before and after the text.

This is inline code: `code`
This is inline code: ``code``

The later form is particularly useful when a ´`´ is part of the code, because escaping delimiters with ´\´ is not possible.

Images

Images are defined using the following syntax:

This is an image: ![This is the image alt text](picture.jpg)

Whitespace characters and new lines are allowed between alt text and image URL:

This is an image: ![This is the image alt text]
(picture.jpg)

Links are defined using the following syntax:

To learn more about blogc, [click here](https://blogc.rgm.io).

Whitespace characters and new lines are allowed between link text and link URL:

To learn more about blogc, [click here]
(https://blogc.rgm.io).

Links can be combined with images:

[![This is the image alt text](picture.jpg)](https://blogc.rgm.io)

Whitespace characters and new lines are allowed between link text and link URL, and between alt text and image URL:

[![This is the image alt text]
(picture.jpg)]
(https://blogc.rgm.io)

Automatic link is defined with 2 ´[´ before and 2 ´]´ after the URL.

To learn more about blogc, visit [[https://blogc.rgm.io]].

Line break

Line breaks can be added after a paragraph line adding 2 or more white spaces to the end of the line.

En dashes and Em dashes

Sequences of 2 ´-´ characters are converted to an En dash HTML entity. Sequences of 3 ´-´ characters are converted to an Em dash HTML entity.

BUGS

The source content is handled by handwritten parsers, that even being well tested, may be subject of parsing bugs. Please report any issues to: https://github.com/blogc/blogc

AUTHOR

Rafael G. Martins <rafael@rafaelmartins.eng.br>

SEE ALSO

blogc(1), blogc-template(7), strftime(3)

January 2021 Rafael G. Martins