search

asciidoctor / jekyll-asciidoc

:syringe: A Jekyll plugin that converts AsciiDoc source files in your site to HTML pages using Asciidoctor.
https://github.com/asciidoctor/jekyll-asciidoc
MIT License
311 stars 78 forks source link

README needs "How to Lobby Steps" #26

Closed jaredmorgs closed 8 years ago

jaredmorgs commented 9 years ago

I scrolled down to the caveat about the plug-in not being whitelisted on GitHub Pages, and I wanted to lobby to get this plug-in added. But how do I actually go about doing that? It would be great to give terse instructions about what passionate users can do to help asciidoctor get weight behind the movement.

I have a vested interest in lobbying for GitHub Pages Whitelist support because I use Jekyll and GitHub Pages exclusively on my tablet, so I don't have a way of post-processing the HTML using a local CI server.

mojavelinux commented 9 years ago

But how do I actually go about doing that?

Whenever I ask GitHub about this, they always say the same thing. Send an e-mail to support using the contact form.

https://github.com/contact

I have a vested interest in lobbying for GitHub Pages Whitelist support because I use Jekyll and GitHub Pages exclusively on my tablet, so I don't have a way of post-processing the HTML using a local CI server.

There is a way to accomplish this by leveraging a combination of CI services like Travis and GitHub webhooks, but we are missing a dedicated guide on the topic. You can find some of the essential information in @eshepelyuk's blog post: http://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html. All we are doing is emulating the setup that GitHub Pages is using...expect we can add whatever plugins we want ;) There's no magic happening here, though GitHub Pages definitely leaves that impression.

mojavelinux commented 9 years ago

Here's a template:

Dear GitHub,

Would you please whitelist the jekyll-asciidoc plugin for GitHub Pages? I would love to use AsciiDoc format on GitHub Pages seamlessly.

I'd be happy to add this information to the README. Great idea!

jaredmorgs commented 9 years ago

Maybe this response should be moved back up to the asciidoctor root. I'm going to talk about my experience as a new user trying to decide between MarkDown and AsciiDoc for my Jekyll GitHub Pages blog.

Set-up comparisons

Travis approach

I've taken a look at eshepelyuk's blog on Travis, and I'll confess I had to read it about four times before I "got it'. Furthermore, I had to jump off that page to two other pages with arguably just as much info. There's gotta be a better way of easing folks into setting this up. ;)

jekyll-now approach

  1. Fork the repo,
  2. Make some _config.yml changes which are clearly explained in the file.
  3. Git commit and push to master
  4. Site is live.

You're quite literally blogging in about 5 minutes tops. And not a PC in sight.

Observations

I'll concede that this is because MarkDown transformation is native, and it takes a pile of config out of the equation.

For the record, I'm not trying to blame AsciiDoc or AsciiDoctor for this, I'm just commenting as a user which approach I'd prefer.

Suggestions

My feeling is that if you could somehow provide an "AsciiDoc-Jekyll" repo with most of the config done or some sort of bootstrapper that folks on supported AsciiDoctor platforms could run, it would be a really easy sell. Maybe an Open Shift cartridge or something, with a start-up script that guides you through could be an option?

I know Open Shift Online lets you set up a WordPress blog in this way, so having an AsciiDoc Jekyll blog would be pretty cool to have alongside this offering, right? On Jan 16, 2015 7:39 PM, "Dan Allen" notifications@github.com wrote:

But how do I actually go about doing that?

Whenever I ask GitHub about this, they always say the same thing. Send an e-mail to support using the contact form.

https://github.com/contact

I have a vested interest in lobbying for GitHub Pages Whitelist support because I use Jekyll and GitHub Pages exclusively on my tablet, so I don't have a way of post-processing the HTML using a local CI server.

There is a way to accomplish this by leveraging a combination of CI services like Travis and GitHub webhooks, but we are missing a dedicated guide on the topic. You can find some of the essential information in @eshepelyuk https://github.com/eshepelyuk's blog post: http://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html. All we are doing is emulating the setup that GitHub Pages is using...expect we can add whatever plugins we want ;) There's no magic happening here, though GitHub Pages definitely leaves that impression.

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/jekyll-asciidoc/issues/26#issuecomment-70229465 .

jirutka commented 9 years ago

You can find some of the essential information in @eshepelyuk's blog post: http://eshepelyuk.github.io/2014/10/28/automate-github-pages-travisci.html.

I’ve used this as a starting point, but the presented script is not very good, so I wrote this rake task: https://gist.github.com/jirutka/79d5810028b994018fc2 (use rake-jekyll instead).

It’s heavily inspired by @razor-x’s blog post: Automatic publishing to GitHub Pages with Travis CI.

I’ll rewrite it as an includable library task, write some howto and send PR to this repo.

jirutka commented 9 years ago

Maybe an Open Shift cartridge or something, with a start-up script that guides you through could be an option?

Wait, what? This seems like a huge overkill for such a simple thing.

johncarl81 commented 9 years ago

A related thought this morning: Could we create a start-up project with all the necessary files and maybe some embedded instructions that people could fork to get up and running quick?

mojavelinux commented 9 years ago

Could we create a start-up project with all the necessary files and maybe some embedded instructions that people could fork to get up and running quick?

Good idea. I've been using a local site project to test the plugin but haven't gotten around to publishing it yet. We should join forces to put a nice starting point together (which would include some of the initial polishing that normally needs to be done). If we do it, I propose we name the repository something like jekyll-asciidoc-quickstart or something.

johncarl81 commented 9 years ago

:+1: I can throw something together this weekend if you'd like.

jaredmorgs commented 9 years ago

Sounds great! This is exactly what the Jekyll-now repo did on the markdown side of things. Makes that initial barrier to entry much lower. On Jan 17, 2015 3:06 AM, "Dan Allen" notifications@github.com wrote:

Could we create a start-up project with all the necessary files and maybe some embedded instructions that people could fork to get up and running quick?

Good idea. I've been using a local site project to test the plugin but haven't gotten around to publishing it yet. We should join forces to put a nice starting point together (which would include some of the initial polishing that normally needs to be done). If we do it, I propose we name the repository something like jekyll-asciidoc-quickstart or something.

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/jekyll-asciidoc/issues/26#issuecomment-70285939 .

jaredmorgs commented 9 years ago

John/Dan

Thank you both for taking on this task. Folks like me that are both new to Jekyll and AsciiDoc will thank you for the effort.

If you can somehow make the repo you're collaborating on also compatible with Blender and Travis, folks that primarily wanted to author on a device other than a PC (like an Android or iOS tablet) would be well-served as well.

At a top level:

  1. Fork the repo.
  2. Follow the readme.adoc which contains clear guidance how to
    • Configure the repo.
    • Configure blender.
    • Configure Travis CI.
  3. Trigger a build.

Then from this point, a user could get the same functionality as the jekyll-now repo offers except with the power of AsciiDoc:

  1. Write .adoc on their device.
  2. Commit using a mobile Git client.
  3. Let Travis CI take it from there and build the site and push to user.github.io

I'd be delighted to review the instructions and test them for you guys as a "new user". On Jan 17, 2015 3:10 AM, "John Ericksen" notifications@github.com wrote:

[image: :+1:] I can throw something together this weekend if you'd like.

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/jekyll-asciidoc/issues/26#issuecomment-70286575 .

johncarl81 commented 9 years ago

Not quite ready yet, but here's the repo: https://github.com/asciidoctor/jekyll-asciidoc-quickstart

jaredmorgs commented 9 years ago

Looks like it's coming along nicely John. Thanks for your work to get it compatible for Travis CI. On Jan 18, 2015 1:59 AM, "John Ericksen" notifications@github.com wrote:

Not quite ready yet, but here's the repo: https://github.com/asciidoctor/jekyll-asciidoc-quickstart

— Reply to this email directly or view it on GitHub https://github.com/asciidoctor/jekyll-asciidoc/issues/26#issuecomment-70372050 .

jirutka commented 9 years ago

I’ll rewrite it as an includable library task, write some howto and send PR to this repo.

I eventually created a separate gem rake-jekyll with Rake tasks for Jekyll, currently just a robust task for deployment to git. I’ve already sent pull-request to jekyll-asciidoc-quickstart.

eshepelyuk commented 9 years ago

Just my 5¢. Instead of creating separate gem containing rake tasks, we could implement Jekyll subcommand as described on their site directly in the current plugin. This way jekyll-asciidoc would be a single dependency for having all required functionality for integrating AciiDoctor with Jekyll.

jirutka commented 9 years ago

The responsibility of jekyll-asciidoc gem is converting of AsciiDoc pages using Asciidoctor to HTML. Deploying of a generated site using Git (or rsync, scp, FTP, pigeons…) is another task that is unrelated to AsciiDoc. That’s why I’ve packaged it as a separate gem — it can be used independently, not just with AsciiDoc and also not just with Travis or GitHub. And most importantly, without stupid copy&pasting of half-working bunch of code across projects…

This way jekyll-asciidoc would be a single dependency for having all required functionality for integrating AciiDoctor with Jekyll.

It already is. Deploying of generated sites to GitHub Pages isn’t required to integrate Asciidoctor with Jekyll. Not everyone needs to deploy Jekyll site to GitHub Pages. It’s just about adding one line to Gemfile and one line to Rakefile.

Instead of … rake tasks, we could implement Jekyll subcommand…

IMHO rake is better suited for a deployment task (more flexible).

jaredmorgs commented 9 years ago

Just my 5¢. Instead of creating separate gem containing rake tasks, we could implement Jekyll subcommand as described on their site directly in the current plugin. This way jekyll-asciidoc would be a single dependency for having all required functionality for integrating AciiDoctor with Jekyll.

It would certainly make jekyll-asciidoc attractive to GitHub if it "just worked". I'm sure it would have the effect of cutting down any perceived adoption barriers on their end.

It already is. Deploying of generated sites to GitHub Pages isn’t required to integrate Asciidoctor with Jekyll. Not everyone needs to deploy Jekyll site to GitHub Pages. It’s just about adding one line to Gemfile and one line to Rakefile.

I'm not wanting to speak for @eshepelyuk here @jirutka . If I understand @eshepelyuk's intent, he wants to make jekyll-asciidoc the solution that GitHub pages uses to transform .adoc in --safe mode, and get it whitelisted. Do other whitelisted converters have the sub-command declared? If so, I would suggest adopting the idea.

@jirutka does raise a valid point that some folks just don't need this functionality. How about an option to turn this on or off? On by default?

jirutka commented 9 years ago

…he wants to make jekyll-asciidoc the solution that GitHub pages uses to transform .adoc in --safe mode, and get it whitelisted.

Once GitHub whitelists the jekyll-asciidoc plugin, then this complicated deploy task will not be needed anymore! You’ll just push pages in AsciiDoc to gh-pages branch and GitHub will generate a static site, just like with Markdown. So that’s just another reason to not copy&paste it to the plugin.

jaredmorgs commented 9 years ago

Once GitHub whitelists the jekyll-asciidoc plugin, then the current complicated deploy task will not be needed anymore! So that’s just another reason to not copy&paste it to the plugin.

OK, fair enough. Thanks for clarifying @jirutka

For the record, I've done my lobbying directly to GitHub:

Steven! Ragnarök wrote: Thanks for the suggestion Jared. I've passed it on to our Pages team to review.

Cheers, Steven!

I've also written http://jaredmorgs.github.io/whitelist-jekyll-asciidoc-for-github-pages/ and have begun sharing it widely.

mojavelinux commented 9 years ago

Btw, I really like that we started with goals (from the blog post by @jaredmorgs)

  1. Fork the repo: your default blog is live!
  2. Make a few changes to the _config.yml file.
  3. Commit and Push.
  4. Your customized blog is live!

I wish every issue had this level of clarity. Bravo!

mojavelinux commented 9 years ago

I also enjoy the irony of you writing blog posts in Markdown to lobby for AsciiDoc. That makes my day :)

jaredmorgs commented 9 years ago

@mojavelinux You're welcome. Red Hat has drummed into me how to "talk to developers" and raise RFEs. I write far too many of these for the Android products I beta test ;)

And, yes, writing blog posts in Markdown is exactly why I'm lobbying for AsciiDoc ;)

You might also be interested that I'm spreading this message to techy mailing lists inside Red Hat (you'd know the ones) and blogging about the initiative on the Customer Content Services blog. I'm pushing the message as far and wide as my networks allow. Let's make this happen!

DavidGamba commented 9 years ago

The responsibility of jekyll-asciidoc gem is converting of AsciiDoc pages using Asciidoctor to HTML. Deploying of a generated site using Git (or rsync, scp, FTP, pigeons…) is another task that is unrelated to AsciiDoc.

I agree, I use jekyll-asciidoc to generate my website and a bash script to push my website to amazon s3. I don't see how the publishing part directly relates to Asciidoc, it is more of a Jekyll compatibility thing.

mojavelinux commented 9 years ago

You might also be interested that I'm spreading this message to techy mailing lists inside Red Hat (you'd know the ones) and blogging about the initiative on the Customer Content Services blog. I'm pushing the message as far and wide as my networks allow. Let's make this happen!

Thank you!!! That is really going to help add fuel to keep this :fire: burning strong.

mojavelinux commented 9 years ago

Not quite ready yet, but here's the repo: https://github.com/asciidoctor/jekyll-asciidoc-quickstart

You are a champion, @johncarl81! This is going to be awesome.

mojavelinux commented 9 years ago

I looked at my local test site and I didn't really have anything to add, other than a sample post...though it looks like you have that underway already. Proceed!

johncarl81 commented 9 years ago

A quick update, we're rounding out the jekyll-asciidoc-quickstart project and I believe we're close to an official release. I went ahead and rebased and created a couple of sites off of this quickstart: http://androidtransfuse.org http://parceler.org http://johncarl81.github.io

I have to say, this makes the site startup a breeze.

Any feedback would be appreciated.

johncarl81 commented 9 years ago

By the way, it looks like newlines without spaces are triggering a <br>. Is there a setting to only do this on double newlines?

johncarl81 commented 9 years ago

Answered my own question regarding the linebreaks. I need to read the READMEs better: https://github.com/asciidoctor/jekyll-asciidoc#hard-line-breaks

mojavelinux commented 8 years ago

Anyone following this thread may be interested to note that GitLab Pages allows you to run Jekyll using a custom launch configuration (including the use of this plugin). In other words, you get exactly what you get on GitHub Pages, except you get to control how Jekyll is executed (no more black box). See https://about.gitlab.com/2016/04/07/gitlab-pages-setup/ for details.

mojavelinux commented 8 years ago

Once GitHub whitelists the jekyll-asciidoc plugin, then this complicated deploy task will not be needed anymore!

Or you can just use GitLab Pages, which works exactly the same way as GitHub Pages (functionally speaking) except it gives you 100% over the build. I have document this in the README.

mojavelinux commented 8 years ago

I think this issue is complete. We have documented all the things mentioned in this issue and the quickstart project has been established. Anything else we need to do?

jirutka commented 8 years ago

Except GitLab.com (hosted instance) is slow and unreliable as hell...

mojavelinux commented 8 years ago

Certainly the performance and reliability of GitLab have to be taken into consideration. I was speaking purely in terms of functionality.

sboekhoff commented 8 years ago

@jirutka : You can install a runner on your local machine: See e.g. https://github.com/sboekhoff/jekyll-asciidoc-docker#use-image-for-gitlab-ci-runner . If you use Docker, it's just 2 commands to get started.

jaredmorgs commented 8 years ago

I was able to find a number of different methods to host static sites on GitLab.

https://gitlab.com/groups/pages

The concept of the GitLab Runner YML config file that lives in the repo is truly an excellent way to describe how a project builds.

Was able to set up Middleman to continuously build a site we use internally with a minimum of fuss.

On Sun, 29 May 2016 at 17:58 Dan Allen notifications@github.com wrote:

Anyone following this thread may be interested to note that GitLab Pages allows you to run Jekyll using a custom launch configuration (including the use of this plugin). In other words, you get exactly what you get on GitHub Pages, except you get to control how Jekyll is executed (no more black box). See https://about.gitlab.com/2016/04/07/gitlab-pages-setup/ for details.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/asciidoctor/jekyll-asciidoc/issues/26#issuecomment-222347930, or mute the thread https://github.com/notifications/unsubscribe/AA6J2ZEHbK8NsEA2OvJiP0ha5226wzlcks5qGUcagaJpZM4DTDr3 .

Sent from Mobile.