BLOGC-SOURCE(7)

📦
version 0.20.1^20240602.b1ae9c9 · 3 versions
, in fedora 43

💖 BLOGC-SOURCE 💖

okay bestie, welcome to the blogc-source(7) era — this is the page in the blogc Manual that explains blogc's source file format. grab a strawberry 🍓 and let's get into it, because this is genuinely the cutest little markup language you've ever met.

✨ NAME ✨

blogc-source — blogc's source file format. that's it, that's the vibe. 🎀

🌸 DESCRIPTION 🌸

so. source files are the input data that gets fed to the blogc(1) compiler. they're where you put your variables and your content, and then the compiler uses all of that to fill in the gaps left in your templates (peep blogc-template(7) for the template lore).

the syntax is designed to be as simple as possible — like, aggressively simple, on purpose. variables go at the top of the file as key-value lines, and the content lives right after the variables. that's the whole layout. periodt. 💅

the content itself is written in a markup language that looks like John Gruber's Markdown, but it is NOT Markdown. like, it's giving Markdown but it is not that. this language is very simple, while still being powerful enough to write big posts. no cap.

your content must be valid UTF-8. that's non-negotiable, bestie. 😭

👑 SOURCE VARIABLES 👑

variables are key-value lines. the rules for the name: it must be upper-case, it starts with a letter, and then it's followed by one or more letters and/or underscores. the value is separated from the variable name with a ':' and it finishes at the end of the line. multi-line values are not supported, sorry 🫶

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

every variable you define in a source file is local, and it will override the global variables you handed to blogc(1) on the command-line — but only inside blocks that handle local variables. for the details on that, go read blogc-template(7).

DATE is the special one 👑 — it represents the publishing date of the post. it may be formatted with the DATE_FORMAT variable, if you provide one; otherwise it gets kept as is. the proper way to access the date from your template is to use the DATE_FORMATTED variable, which will hold the formatted date, or the original date, depending on whether you provided DATE_FORMAT or not.

DATE should be in this format: yyyy-mm-dd hh:mm:ss. you can totally omit the seconds, minutes and hours if you want — they get filled with '0'. the allowed formats are:

  • yyyy-mm-dd hh:mm:ss
  • yyyy-mm-dd hh:mm
  • yyyy-mm-dd hh
  • yyyy-mm-dd

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

the source parser also auto-generates a variable called FILENAME, which stores the name of the source file without its extension. this is so useful for building permalinks in templates. this variable can't be overriden by an explicit definition in the source file. 🚫

the variable FIRST_HEADER is created by the source parser by default, and it contains 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 the source file — and if you do that, the HTML entities must be escaped manually.

another one: DESCRIPTION gets automatically created by the source parser. it contains the unparsed content of the first paragraph found in the source file. content is not parsed, but HTML entities are encoded. paragraphs inside blockquotes are ignored. this variable can also be overriden by an explicit definition in the source file, and that definition must have the HTML entities escaped manually too. this is super handy for adding "description" meta-tags to HTML templates. you might need to truncate the variable size to a maximum length — take a look at blogc-template(7) for that. 🦋

🌈 SOURCE CONTENT - BLOCK ELEMENTS 🌈

🎀 Paragraphs

paragraphs are simple blocks of text. iconic behaviour.

This is a paragraph.

This is another paragraph.

🎀 Headers

headers start with '#' characters, and the number of characters is the level of the header. levels, bestie, we love a hierarchy.

# H1

## H2

### H3

#### H4

every header gets an id attribute, which 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. slay 🔥

🎀 Blockquotes

blockquotes are defined with lines starting with '>' characters. content inside a blockquote is parsed again, so literally all the block elements are allowed inside blockquotes. the indentation after the '>' character must be preserved at the beginning of each blockquote line. don't skip that part 🙈

> 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 at the beginning 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 at the beginning of each line, meaning the content of the items must be aligned. the order and value of the numbers is ignored. yes, ignored. the numbers are lying to you and that's fine 💀

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 a '.' 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 a '<' character. everything is kept untouched in HTML blocks, until the next paragraph. raw, unfiltered, no notes. 💅

<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. so nothing gets lost, it's just ✨ demarcated ✨.

🦋 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 by mixing the 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 latter form is especially useful when a '`' is part of the code, because escaping delimiters with '' is not possible. that's the whole reason it exists, iykyk 🧚

💜 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 the alt text and the 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 the link text and the 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)

an 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 by adding 2 or more white spaces to the end of the line. sneaky but effective 🌸

💜 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. dashes getting a whole glow-up, obsessed ✨

💀 BUGS 💀

the source content is handled by handwritten parsers, and even though they're well tested, they may be subject to parsing bugs. if you find an issue, please report it to: https://github.com/blogc/blogc — do it for the girlies 🫶

⭐ AUTHOR ⭐

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

🌟 SEE ALSO 🌟

and that's the whole page, bestie!! this one came from Rafael G. Martins, dated January 2025, in the blogc Manual — go forth and write the cutest little source files, you absolute main character 👑💖✨

📦 where this page comes from