From ecb00611a359ef1b324efee3d37b22e455bb6be4 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Tue, 30 Oct 2018 13:11:32 -0600 Subject: [PATCH] explain how to include the document title on the generated page --- README.adoc | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/README.adoc b/README.adoc index 3acf312..186c708 100644 --- a/README.adoc +++ b/README.adoc @@ -245,6 +245,45 @@ In addition to page attributes defined explicitly (e.g., layout, permalink, etc) * author * revdate (becomes date; value is converted to a DateTime object; posts only) +==== Showing the Document Title + +By default, when Asciidoctor converts your document, it does not include the document title in the body (aka `content`) part of the document that is passed to the layout. +Instead, it skims off the document title and assigns it to the model as `page.title`. +If you don't see the document title on the generated page at first, that's normal. + +There are two ways to have the document title included in the page: + +. Configure the layout to output the document title explicitly +. Configure Asciidoctor to include the document title in the body + +The first option is the most typical. +Somewhere in your layout, you should include the following statement: + +---- +

{{ page.title }}

+---- + +This approach gives you the most control over how the document title appears and what HTML is used to enclose it. + +If, instead, you want the document title to be included in the body, add the following configuration to your site's {path-config} file: + +[source,yaml] +---- +asciidoctor: + attributes: + - showtitle=@ +---- + +It's also possible to enable or override this setting per page. + +[source,asciidoc] +---- += Page Title +:showtitle: +---- + +Using either of these approaches, the document title will be shown on the generated page. + ==== Giving Your Post the Time of Day By default, all posts are assigned a date that is computed from the file name (e.g., the date for 2016-03-20-welcome.adoc is 2016-03-20).