The couple ASCIIDOC + AWESTRUCT

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

The couple ASCIIDOC + AWESTRUCT

fleurystephane
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
Reply | Threaded
Open this post in threaded view
|

Re: The couple ASCIIDOC + AWESTRUCT

LightGuardjp
Administrator
Unless Dan has some brilliant idea, I'd have to think about this one for a bit.


On Fri, Aug 23, 2013 at 9:33 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



--
Reply | Threaded
Open this post in threaded view
|

Re: The couple ASCIIDOC + AWESTRUCT

mojavelinux
Administrator
In reply to this post by fleurystephane
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



--
Reply | Threaded
Open this post in threaded view
|

Re: The couple ASCIIDOC + AWESTRUCT

fleurystephane
Dan,

Thank you very much for your detailed response.

I chose the solution B with tag, and it works very well!
I prefer to add tags rather than cut my files for a special output.

I have now to study the way I will store the doc files, we don't use Git at work... :(

One last question :
What is the best way to declare the layout in my getting-started.adoc file ?
:awestruct-layout: started
include::docs/part1.adoc[tags=getting-started]

OR

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



Thank you again for your work

Stéphane
Reply | Threaded
Open this post in threaded view
|

Re: The couple ASCIIDOC + AWESTRUCT

LightGuardjp
Administrator
Which scm are you using? HEAD in awestruct has a new thin (very thin) layer for scm checking on publish. It would be a good simple enhancement to contribute. 

Sent from Mailbox for iPhone


On Sat, Aug 24, 2013 at 1:37 AM, fleurystephane [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Dan,

Thank you very much for your detailed response.

I chose the solution B with tag, and it works very well!
I prefer to add tags rather than cut my files for a special output.

I have now to study the way I will store the doc files, we don't use Git at work... :(

One last question :
What is the best way to declare the layout in my getting-started.adoc file ?
:awestruct-layout: started
include::docs/part1.adoc[tags=getting-started]

OR

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



Thank you again for your work

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-tp513p516.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: The couple ASCIIDOC + AWESTRUCT

fleurystephane
Reply | Threaded
Open this post in threaded view
|

Re: The couple ASCIIDOC + AWESTRUCT

LightGuardjp
Administrator
That's a new one, haven't heard of it. Is it big in France?

Sent from Mailbox for iPhone


On Mon, Aug 26, 2013 at 3:59 AM, fleurystephane [via Asciidoctor :: Discussion] <[hidden email]> wrote:

We use Serena Dimensions CM


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/The-couple-ASCIIDOC-AWESTRUCT-tp513p524.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML