Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
14 posts
|
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
354 posts
|
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, ... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
2681 posts
|
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..docs/chapter1.adoc [source,asciidoc] --
= Chapter 1: Name of ChapterPerhaps it's more than one paragraph. -- 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-layoutInformation 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, ... [show rest of quote] -- Dan Allen | http://google.com/profiles/dan.j.allen |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
14 posts
|
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 |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
354 posts
|
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:
... [show rest of quote] |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
14 posts
|
We use Serena Dimensions CM
|
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
354 posts
|
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:
|
Free forum by Nabble | Edit this page |