search

asciidoctor / jekyll-asciidoc-quickstart

A template project for creating AsciiDoc-based websites using Jekyll.
https://asciidoctor.github.io/jekyll-asciidoc-quickstart/
MIT License
124 stars 158 forks source link

Repurpose JAQ for Mini Docs Sites #10

Closed jaredmorgs closed 8 years ago

jaredmorgs commented 9 years ago

@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:

What we're having issues with:

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

jaredmorgs commented 9 years ago

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

categories:

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

jaredmorgs commented 9 years ago

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 commented 9 years ago

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. :-1:

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 commented 9 years ago

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:

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 commented 8 years ago

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 commented 8 years ago

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 https://github.com/asciidoctor/jekyll-asciidoc-quickstart/issues/10#issuecomment-161834652 .

Sent from Mobile.

johncarl81 commented 8 years ago

@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.