organizing many asciidoctor generated html documents

classic Classic list List threaded Threaded
6 messages Options
a4z
Reply | Threaded
Open this post in threaded view
|

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
|

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
|

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
|

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

Re: organizing many asciidoctor generated html documents

a4z
Solved the problem this way:

rake file goes through the folder structure, generates a new TOC.adoc if the file tree has changed.
since rake knows the location of each document it can generate a navigation path
root/you/are/here
and pass this via an attribute to the document generation. Together with a link to the generated TOC.
I have learned a little bit about the asciidoctor back ends, so this plays nicely together

Together with guard and live reload,  the new TOC and navigation link in the documents, writing documentation makes more fun than ever.

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

Re: organizing many asciidoctor generated html documents

arillbert
Hi.
I'm glad you found a way to do this.

I had a similar need. I wanted to auto-generate html/pdf from adoc files that reside in a git repo together with our source code.

I have written 'giblish', a gem that uses asciidoc/asciidoc-pdf to generate docs from different branches and tags in a git repo and generate clickable index pages that show an overview of the 'site'. At work, I use giblish together with git server side hooks to auto-generate and publish our documentation at commits to our product branches.

If you want to take a look, you can install it via 'gem install giblish' or check out the github project at https://github.com/rillbert/giblish

Cheers