Adding a block title in Asciidoctor is easily done by adding a line at the top of the block that starts with a dot (.). The text following the dot is then used as the title of the block. But if the text of the title itself starts with a dot (.) Asciidoctor get's confused. For example if we want to use a filename that starts with a dot (.filename) we must use different syntax to set the block title with the filename.
In the next Ascciidoc markup sample we use different ways to set the block title for a code block with a filename that starts with a dot. First we use the title attribute for the block. Another solution is to use the Unicode value for the dot. Next we enclose the filename in back ticks (`) which also formats the filename with a monotype font. We can also separate the first dot with the dotted filename with the document attribute {blank}. Also we can define the dot as document attribute and use it in the title. And finally we can define the filename via a document attribute and reference the document attribute in the block title:
= Filenames starting with dot (.)
Several samples showing how to set block title when title starts with dot (`.`).
Code block title is filename that starts with dot (`.`), which confuses the parser:
[source,json]
// Title cannot be parsed correctly
// because of the 2 dots.
..eslintrc
----
{
"key": "value"
}
----
Using explicit title attribute:
// Instead of using . notation
// for block title, we use the
// explicit block attribute
// title definition.
[source,json,title='.eslintrc']
----
{
"key": "value"
}
----
Use Unicode value for dot:
[source,json]
// Use hexadecimal Unicode replacement for
// starting dot (.) in filename.
..eslintrc
// (Or with decimals: ..eslintrc)
----
{
"key": "value"
}
----
Format filename as code:
[source,json]
// Put filename between back ticks (`)
// and title is recognized again and
// nicely formatted with monotype font.
.`.eslintrc`
----
{
"key": "value"
}
----
Using `\{blank}` document attribute to separate
title dot and filename:
[source,json]
// Separate title and filename with
// {blank} document attribute.
.{blank}.eslintrc
----
{
"key": "value"
}
----
Using document attribute to define dot and use with filename:
[source,json]
// Section title is also parsed correctly
// if we use a document attribute
// to reflect dot.
:dot: .
.{dot}eslintrc
----
{
"key": "value"
}
----
Using document attribute to set filename:
[source,json]
// Section title is also parsed correctly
// if we use a document attribute
// with the filename.
:snippetFilename: .eslintrc
.{snippetFilename}
----
{
"key": "value"
}
----
[source,json]
// We can re-use the same document attribute
// for other code sections.
:snippetFilename: .jslintrc
.{snippetFilename}
----
{
"key": "value"
}
----
When we generate a HTML version of this markup we get the following result:
Written with Asciidoctor 1.5.4
