Asciidoctor :: Discussion - Re: The couple ASCIIDOC + AWESTRUCT

Re: The couple ASCIIDOC + AWESTRUCT

Posted by mojavelinux on
URL: https://discuss.asciidoctor.org/The-couple-ASCIIDOC-AWESTRUCT-tp513p515.html

Hey there Stéphane! We're glad your excited about this powerful duo.

There are two ways you can render fragments (chunks) of AsciiDoc content on a site built with Awestruct. Both solutions involve using the include::[] directive.

First, let's assume you have a file named docs/chapter1.adoc with the following content (inside the source block):

.docs/chapter1.adoc

[source,asciidoc]

= Chapter 1: Name of Chapter

== Gettting Started

Information on getting started.

Perhaps it's more than one paragraph.

== Other Content

More content.
--

Solution A ::

The first solution for rendering only the getting started chunk is to move it to an include file, perhaps docs/sections/getting-started.adoc.

.docs/sections/getting-started.adoc

[source,asciidoc]
--

= Getting Started

:awestruct-layout: my-layout

Information on getting started.

Perhaps it's more than one paragraph.

Then you can include that with your chapter content:

.docs/chapter1.adoc[]

[source,asciidoc]
--
= Chapter 1: Name of Chapter

:leveloffset: 1

include::sections/getting-started.adoc[]

:leveloffset: 0

== Other Content

More content.
--

The getting-started.adoc can now be rendered on it's own (as you can see by the awestruct-layout attribute), or you could remove that attribute from the docs/sections/getting-started.adoc and create a dedicated page file named getting-started.adoc at the root of the site that includes the docs/sections/getting-started.adoc content.

// this becomes a page in Awestruct

.getting-started-page.adoc

[source,asciidoc]

:awestruct-layout: my-layout

include::docs/sections/getting-started.adoc[]

You'll have to play around with the paths to make sure the parent documents can find the include files. You'll also need to adjust the leveloffset according to how you decide to store it. The leveloffset allows you to shift all the heading levels when you want to embed the content or use it as top-level. (In the future, leveloffset will be an attribute on the include directive).

Option B::

The other option is to leverage the feature in Asciidoctor to include file fragments. The most robust approach is to use tags in the content that you can extract. First, we tag the content in docs/chapter1.adoc.

.docs/chapter1.adoc
[source,asciidoc]
--
= Chapter 1: Name of Chapter

// tag::getting-started[]

== Gettting Started

Information on getting started.

Perhaps it's more than one paragraph.

// end::getting-started[]

== Other Content

More content.
--

Then you create a page at the root of the site that includes this content and gives it a layout.

.getting-started.adoc[]

[source,asciidoc]
--

:awestruct-layout: my-layout

include::docs/chapter1.adoc[tags=getting-started]

(In the future, we'd like to be able to extract structured content for AsciiDoc files, but we aren't there yet).

Admittedly, it takes a few steps to get setup, but once you have it going, it should feel quite organized.

I recommend puts the docs in a separate git repository, then including it in the website repository as a submodule. Thus, you're website repo would be structured like:

.awestruct_ignore

_config/

site.yml

_ext/

pipeline.rb

_layouts/

docs/

sections/

getting-started.adoc

chapter1.adoc

images/

javascripts/

stylesheets/

Rakefile

Gemfile

index.html

getting-started.adoc

If you don't want your docs folder to get rendered in Awestruct, you'll want to add it to the .awestruct_ignore file:

.awestruct_ignore
----

Gemfile
Gemfile.lock
...

docs

----

Another solution is to name the submodule folder _docs. Any directory that is prefixed by an underscore is ignored by Awestruct when looking for pages.

I hope that helps! If you have follow-up questions, feel free to ask.

-Dan

p.s. If you're using includes, you'll definitely want to use Asciidoctor 0.1.4 (as soon as it's released) since it correctly handles relative include paths and gives better diagnostic information when something is wrong inside an include file.

On Fri, Aug 23, 2013 at 9:32 AM, fleurystephane [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hello,

I'm AWESTRUCT! I'm ASCIIDOC!
Ok, but I have a question :
When I write my documentation files (structured as a book : Preface, Part 1, chapter 1,2,3, Part 2, chapter 1,2...), I don't have to worry with the output generation (HTML, PDF,...). If I use awestruct + bootstrap, it's not possible (or difficult) to keep the organisation of asciidoc files :
Let's suppose that I write a file named chapter1.adoc, this file contains the getting started paragraph and many other things. How can I use this chapter1.adoc with a layout for rendering only the getting started paragraph ?

I think according my understanding that the asciidoc files have to be rewritten for html site with awestruct ??

Thanks for your answers!

Stéphane

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/The-couple-ASCIIDOC-AWESTRUCT-tp513.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen