Quantcast

organizing many asciidoctor generated html documents

classic Classic list List threaded Threaded
4 messages Options
a4z
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

organizing many asciidoctor generated html documents

a4z
Hello asciidoctor community

At work I started to write the one or the other asciidoctor document,  than a colleague joined and added some, ...  , and now there are 40 to 50 documents and they still grow since we like this way af generating documentation a lot.

We have all adoc files in a git repo, a build server checks them out, runs some rake file that generates the html documents, and these documents are copied into a shared folder on a Linux machines and reachable via a trac website,
We know how to navigate in these documents, it's a simple tree, there is a root document, and this links do documents in sub folder, and these link to other documents.

So far so good, but now management started also to read this documents, they are happy, but have navigation problems. So I wonder. Is there a predefined way to get on or some of the following when working with multiple documents?

* There is no back button in the footer or some other navigation root/place/place
* There is no global TOC since we have multiple documents, can this be generated or do I need to write a own script
* Some search index from the static sites
 
I have tired to include everything but this is not optimal, we have a lot of links from one doc into others, lots of (asciidoctor) diagrams, picture include, the result becomes juts too big.

I also tried golumn, this is not bad but does now work for many reasons.

Is there some other 'standard' way of dealing with multiple documents and organize them in a wiki like structure/way?

Thanks a lot for help!

my asciidoctor generated website: https://a4z.bitbucket.io/
Ted
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: organizing many asciidoctor generated html documents

Ted
This post was updated on .
a4z wrote
So I wonder. Is there a predefined way to get on or some of the following when working with multiple documents?

* There is no back button in the footer or some other navigation root/place/place
* There is no global TOC since we have multiple documents, can this be generated or do I need to write a own script
* Some search index from the static sites
 
I have tired to include everything but this is not optimal...
I'm still looking for the definitive answer also.

So far there have been some answers that address most of the problem. Take a look at this forum thread: Use AsciiDoctor only for a simple website

I think the main thing that is missing is a search tool. Also I would like to find an easier solution to generating a site wide table of contents (TOC) to link the pages together.

I've been using Hugo, a static website generator like Jekyll. There are some external tools for search Hugo tools (look at Search section) that I have not tried.

With Hugo & Jekyll you get the added benefit of tags & categories you hand-code in the front matter. Overall you could make a documentation website with these, but I'm not sold on the approach of Hugo or Jekyll because Asciidoctor can create a website with one command.

Instead of using front matter, I think creating a script to generate a TOC / sitemap might be better. But you still have to paste that into your header/footer includes to link the documentation website together.

And you still need to add search. Lunr seems like a possible solution.

IMO the goal is a static website generator that creates a searchable documentation website. This is slightly different than Hugo & Jekyll that are geared toward blog posts in dated order. Documentation is grouped by topic not dates.

- Ted @TedAtCIS
Ted
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: organizing many asciidoctor generated html documents

Ted
My personal approach is to link all my .adoc files together using the Asciidoctor live previewer in Chrome

(how to: Local AsciiDoc Website)

I use browser search (Ctrl-F) when I get to the page I think the content is on. However there is no site wide search.

- Ted @TedAtCIS
a4z
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: organizing many asciidoctor generated html documents

a4z
Thanks for the info Ted!

I tried jekyll the last days but it does not really help.

My current setup for this work is
folder hierarchy, 3 or 4 levels deep,
every folder with index and maybe other docs

I have a rake file for generating the html, that also rsync pictures and other resources into the target directory
together with Guard this works super, much better than jekyll.

The problems I have:
1) I need a better navigation than just a back button
2) I need a TOC that goes over the hierarchy and is autogenerated because manual work will lead to dead/wrong entries over time
3) I would like to have some [full] text search

I do not care that much about themening the pages, asciidoctor looks great by default.
in fact, making the jekyll generated site looking like asciidoctor default was one of the big time eater the last days for me.
maybe I did something wrong, or did not understand the concept of jekyll, but I am happy I have chosen awestruct for my blog.

I guess I could auto generate a TOC / site map or something like that,
and also some header/footer for the navigation in the pages, or something on the side, similar to the TOC that asciidoctor generates.
Maybe as a dynamic menu,  
but I do not know how this should look like and currently my HTML knowledge is limited, after all I am from the embedded world :-)
however, this should be solvable with the time,
This should solve 1 and 2.
3 is optional anyway

At the end, after doing some evaluation adding some ruby to my rake file that does this seems to be a much more easy task than using jekyll.
I would not recommend this for a blog, but for documentation in a folder hierarchy it seems there is no solution currently available.
my asciidoctor generated website: https://a4z.bitbucket.io/
Loading...