Repurpose JAQ for Mini Docs Sites

[jaredmorgs]

@johncarl81 and I have been talking about how we can use the work done already with JAQ to help folks stand-up an AsciiDoc Docs Portal

This has come about from my work on the http://jaredmorgs.github.io/Pinball_Arcade_Users_Guide_Android/ which lives in https://github.com/jaredmorgs/Pinball_Arcade_Users_Guide_Android

I'm currently publishing this guide on the computer using Asciidoctor then pushing the index.html to the gh-pages branch. @johncarl81 created a PR on the repo that uses JAQ to publish the guide automatically on commit, very similar to how JAQ does it for blog posts.

The current status of the PR is published at http://johncarl81.github.io/Pinball_Arcade_Users_Guide_Android/

The vision we have is a "fork-and-go" repo with:

• a dynamically created navigation for the docs.
• docs stored in sub-folders in the repo for separation.
• Foundation as the base L&F (because it is so responsive)

What we're having issues with:

• Getting the TOC to work using JAQ.
• Working out how to dynamically make the navigation.

Does anyone have any ideas how we might solve the issues we've seen to date?

[jaredmorgs]

If a dynamically-create navigation isn't possible, perhaps we could repurpose the categories feature and use it like this:

categories:

• Pinball Arcade Users Guide Android
• Zaccaria Pinball Users Guide Android

and use the categories to sort and display the books like you would a blog post?

[jaredmorgs]

This is starting to become important to me again, because I need to set up a static site that has stuff like my Resume, redirect to HubPress, and menu navigation.

I think the index.adoc should be expanded upon to show folks how to use multiple .adoc files to control site structure, and how to declare these files to render the content in the templating system.

[jaredmorgs]

OK, @mojavelinux , @johncarl81 and @jirutka

I've decided to go out on a limb and dragonforce the Lanyon core files atop the JAQ in my own repo.

https://github.com/jaredmorgs/jekyll-asciidoc-quickstart

My brute-force approach has—not surprisingly—not worked. 👎

Jekyll will currently not run when I try jekyll serve and I get a result like:

jaredmorgs:jekyll-asciidoc-quickstart jaredmorgs$ jekyll serve
WARN: Unresolved specs during Gem::Specification.reset:
      listen (~> 3.0)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.
Configuration file: /Users/jaredmorgs/Repos/jekyll-asciidoc-quickstart/_config.yml
            Source: /Users/jaredmorgs/Repos/jekyll-asciidoc-quickstart
       Destination: /Users/jaredmorgs/Repos/jekyll-asciidoc-quickstart/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
Since v3.0, permalinks for pages in subfolders must be relative to the site source directory, not the parent directory. Check http://jekyllrb.com/docs/upgrading/ for more info. 

I have run bundler to update the gems which fixed a lot of the dependency issues I originally had.

I'm sure there's a logical explanation to this, and I'm positive I've screwed something up. But perhaps it's a starting point you guys can use to iterate on.

[jaredmorgs]

OK @mojavelinux @johncarl81 @jirutka

I had some real issues just dumping everything in per my previous post, so I took the sane approach and started with Vanilla Lanyon and added the bits to it.

https://github.com/jaredmorgs/lanyon is building fine with Jekyll 2.5.3, but some issues with relative permalinks throws critical deprecation errors with Jekyll 3.0. Something we'd need to look at moving forward.

Everything is building now, but I've noticed some things that may need to be refined:

• Lanyon defaults to blog as the main Home view, which is probably not the best thing for me (maybe not JAQ) either.
• I can't seem to easily refactor the Home view to display a landing page, so would need to kludge the content in the _posts directory to control what Getting Started info to display.
• If we decide to go with Lanyon, how do we balance using the theme but crediting the original author?

Questions:

1. Could we just reuse some of the sidebar code and make it work with the Zurb templating engine? I would imagine keeping Zurb would be the preferred approach for unified supportability.
2. Based on how the Android User Guide looks, I think it would be beneficial to keep Zurb as the templating engine. It does such a great job.

[mojavelinux]

This is looking pretty amazing. Nice work.

I know that the plugin has some issues with Jekyll 3.0. I think that Paul is going to be doing a new release shortly that should fix it.

I have run bundler to update the gems which fixed a lot of the dependency issues I originally had.

This is the main reason I use rvm. When I come back to an old project, I always use:

$ rvm gemset empty && bundle

That way, I am sure that I start with a clean slate and get only the gems that should be there. I simply don't trust Bundler to operate any other way (and this strategy has really worked for me).

Once you get used to styling Asciidoctor-generated HTML, you'll find that you really don't need to bound to a given CSS framework (Foundation or otherwise). It seems scary at first, but it's worth trying to understand how to style it because then you are free to roam and make whatever CSS you want. The default stylesheet in Asciidoctor just lets you put off that work initially. But it really isn't magic.

[jaredmorgs]

While the changes I've done using lanyon look pretty good, the more I think
about it, the more I'm leaning towards working with a default
Foundation-based template as the baseline.

It would keep the basic templating system in-line with current Asciidoctor
default stylesheets, and would allow better integration with other
Asciidoctor projects.

I do heed your advice about learning how to style the baseline stylesheets
though. My goal with JAQ is to make the barrier of entry as low as possible
for someone coming into static sites with a desire to use Asciidoctor for
content.

I am also aware the wider Asciidoctor contributors are very familiar with
Zurb, so it makes sense to leverage that.

On Fri, 4 Dec 2015 at 10:29 Dan Allen notifications@github.com wrote:

This is looking pretty amazing. Nice work.

I know that the plugin has some issues with Jekyll 3.0. I think that Paul
is going to be doing a new release shortly that should fix it.

I have run bundler to update the gems which fixed a lot of the dependency
issues I originally had.

This is the main reason I use rvm. When I come back to an old project, I
always use:

$ rvm gemset empty && bundle

That way, I am sure that I start with a clean slate and get only the gems
that should be there. I simply don't trust Bundler to operate any other way
(and this strategy has really worked for me).

Once you get used to styling Asciidoctor-generated HTML, you'll find that
you really don't need to bound to a given CSS framework (Foundation or
otherwise). It seems scary at first, but it's worth trying to understand
how to style it because then you are free to roam and make whatever CSS you
want. The default stylesheet in Asciidoctor just lets you put off that work
initially. But it really isn't magic.

—
Reply to this email directly or view it on GitHub
#10 (comment)
.

Sent from Mobile.

[johncarl81]

@jaredmorgs, I've just used the examples from the foundation website to get things working: http://foundation.zurb.com/sites/docs/

Looking over things, I think we've accomplished what we sought after with this issue and the related PRs. I'd like to close this issue if you agree @jaredmorgs.