The GPars website

[Russel Winder]

Václav,

Jim Northrop has been very brave and created a transform of my
Markdown/Jekyll GitHub Pages webpages into ASCIIDoc. The primary goal
was to amend the links to the now defunct Codehaus, but along the way
he is trying to solve the "the current website looks really crap"
problem.

The current thinking is that we can have the website and the user
manual render in the same style, which will give us a nice consistency.
Of course we probably want to do something other than the default
ASCIIDoc style so as to create a brand, but we can almost certainly use
the same styling for both.

Assuming we can get a workflow, I propose merging the user guide source
into the website source and having everything as a single site.

Does this work for you?


All,

Currently the website is in Markdown and processed by Jekyll on pushing
the Git repository. Although there is an ASCIIDoc plugin for Jekyll I
have no idea whether GitHub Pages runs this, and the website is not
that informative. Does anyone know if the Jekyll workflow can be used
with ASCIIDoc on GitHub Pages? Alternatively I assume we have to
process the ASCIIDoc to generated HTML and then push to the mainline
repository avoiding all Jekyll processing. Does anyone have any
experience and/or advice on how to get this working?



--
Russel.
=============================================================================
Dr Russel Winder t: +44 20 7585 2200 voip: sip:russel...@ekiga.net
41 Buckmaster Road m: +44 7770 465 077 xmpp: rus...@winder.org.uk
London SW11 1EN, UK w: www.russel.org.uk skype: russel_winder

[jim northrop]

Thank you for that briefing. 

1. Since my forte is groovy+gradle+asciidoctor+cloud foundry, i followed my heart and used the asciidoctor solution and ignored jekyll. Eventually we can worry about where to host the results, but for now i am currently manually changing each *.md file into an *.adoc file. (about 20 more to go). Then use asciidoctor tool to make an html from that. This is coming along nicely as you can see here: http://a9s.de.a9sapp.eu/  the first level of clickable links should work, so you can get a L&F for the results.

2. There will be a single asciidoctor.css that you will be able to 'theme' to affect the entire set of documents.

3. Have discovered an old css3 menu bar on my backups to sample as a navigation bar. More on this later.

4. Had a little time to review href links and emails in each *.md, the list of pain-points is attached below. If you could pls review and nominate alternates or request each to be deleted/commented out, then i can also adjust the gpars doc.s to reflect your decisions.

5. Time-permitting, after all docs become html, i want to run a script to confirm each <a href/> and email@address is valid. There may be a list from this that you guys will need to address for fixes/deletions,etc.

6. I am happy to do the user manual if you provide a url where i can download that. It would also become an asciidoctor file so we have a common L&F across all GPars documentation. We can either integrate it with the (eventual) navigation bar, or as a bullet-point in the sub-menu doc.page.

7. Eventually i'll write a build.gradle script to automate all this bumph, so we dont need to do it again. Gradle has publisher plugins we might use for uploads to your static site! Hurrah :-)

-------------

Pls review the list below this week, if you can, while i crack on with these other tasks.

More news soon

thanx

Jim

[Russel Winder]

Jim,

> 1. Since my forte is groovy+gradle+asciidoctor+cloud foundry, i
> followed my
> heart and used the asciidoctor solution and ignored jekyll.
> Eventually we
> can worry about where to host the results, but for now i am currently
> manually changing each *.md file into an *.adoc file. (about 20 more
> to
> go). Then use asciidoctor tool to make an html from that. This is
> coming
> along nicely as you can see here: http://a9s.de.a9sapp.eu/
> <http://a9s.de.a9sapp.eu/>  the first level of clickable links should
> work,
> so you can get a L&F for the results.

I think GitHub Pages (gpars.github.io) is the right place to host this,
at least in the short- and medium-term.

So the question is now whether to store the ASCIIDoc source in one
repository and the generated HTML pages in another with the latter
being pushed to change the website, or whether to have all the material
in one repository. I am not entirely sure how to properly structure a
mixed content repository, but I am sure others have already done
something no dissimilar.

> 2. There will be a single asciidoctor.css that you will be able to
> 'theme'
> to affect the entire set of documents.

This sounds good :-)

> 3. Have discovered an old css3 menu bar on my backups to sample as a
> navigation bar. More on this later.
>
> 4. Had a little time to review href links and emails in each *.md,
> the list
> of pain-points is attached below. If you could pls review and
> nominate
> alternates or request each to be deleted/commented out, then i can
> also
> adjust the gpars doc.s to reflect your decisions.

Wilco.

> 5. Time-permitting, after all docs become html, i want to run a
> script to
> confirm each <a href/> and email@address is valid. There may be a
> list from
> this that you guys will need to address for fixes/deletions,etc.
>
> 6. I am happy to do the user manual if you provide a url where i can
> download that. It would also become an asciidoctor file so we have a
> common
> L&F across all GPars documentation. We can either integrate it with
> the
> (eventual) navigation bar, or as a bullet-point in the sub-menu
> doc.page.

The user manual is already in ASCIIDoc :-)

The source is in the main GPars repository in the src/docs/asciidoc
directory.

Interesting question of whether it should stay where it is and we find
a way of copying over generated HTML files to the website repository,
or whether we change the structure of the repositories a bit.

> 7. Eventually i'll write a build.gradle script to automate all this
> bumph,
> so we dont need to do it again. Gradle has publisher plugins we might
> use
> for uploads to your static site! Hurrah :-)

Automation is good :-)

> -------------
> Pls review the list below this week, if you can, while i crack on
> with
> these other tasks.

I'll work on the file attachment. I suspect many of them will have to
remain incomplete until we have a first draft of the new site in place.