Update the "Installing and Using Asciidoctor.js" page

[ggrossetie]

The page is outdated as there are simpler ways to install Asciidoctor.js using npm or Bower package.

[mojavelinux]

In theory, this page should mirror what is in the README of the project. Eventually, we want to automate this linkage. For now, I've been manually synchronizing them. Do you want to just use the same content for now?

[ggrossetie]

Yes that would be more accurate. I also have a pending pull request to rework the README on Asciidoctor.js : https://github.com/asciidoctor/asciidoctor.js/pull/71

Maybe we can merge this pull request before synchronizing the content ? Wdyt ?

[jaredmorgs]

Any action taken on this @Mogztter or @mojavelinux ?

(just cleaning up the older tickets in the project from a docs standpoint)

[mojavelinux]

@jaredmorgs This gets to the root of the information architecture problem we have on asciidoctor.org. Right now, we are copying README files from the component repositories to populate the site. Since it is done manually, sometimes the file gets changed after the fact on the site. That leaves us with divergent documents and a real mess.

We need to switch to using a remote include mechanism. Each repository needs to add include tags for which parts of the README should be snipped and the file on asciidoctor.org should simply includes these regions. That way, no synchronization issue. It also allows us to read the file from a tag instead of from master.

For example:

= Asciidoctor.js

include::https://raw.githubusercontent.com/asciidoctor/asciidoctor.js/v1.5.4-rc.1/README.adoc[tags=region1;region2]

There's still the issue of site layout and which content should go where, but this at least allows us to get away from manually copying content.

@Mogztter would you be able to markup the README in Asciidoctor.org for which sections you want clipped (if not the whole file)?

[mojavelinux]

For example, we don't need the contributing, credits and all that stuff on the page on asciidoctor.org (we're just interested in the documentation).

[mojavelinux]

I also want to update the page name to just "asciidoctorjs" instead of "install-and-use-asciidoctorjs". To make this change,

1. rename the file to asciidoctorjs.adoc

2. add a new file named install-and-use-asciidoctorjs.redirect and populate it with:

   ---
   interpolate: true
   ---
   #{site.base_url}/docs/asciidoctorjs/

The resulting page will be http://asciidoctor.org/docs/asciidoctorjs

(we have to drop the period as it may confuse certain browsers).

[ggrossetie]

@mojavelinux I think you can take the whole file. The "new" REAME gives a good overview of the project and is short enough to be included as is.

[mojavelinux]

Sounds good. Since you've been working a bunch with the site, want to give it a shot?

[mojavelinux]

Note that we could use ifndef::env-site[] in the upstream README to hide certain sections.

[ggrossetie]

Sounds good. Since you've been working a bunch with the site, want to give it a shot?

Yes, sure. Could you please assign this issue to me ?

[mojavelinux]

Assigned.

Don't worry about the URI caching. I looked into it and discovered that open-uri-cached is actually pretty useless. It caches permanently with no option to automatically check for updates. If we have Travis cache the folder, we'd have to clear it out regularly. If Travis does not cache the folder, it fetches the contents from the URI every build anyway. And it seems to do a heck of a lot of work to cache the result (including reading or writing a big YAML file), so even with a patch to open-uri-cached, it is still quicker just to fetch the contents.

If we were grabbing dozens of URIs multiple times, then we'd need something like that.

[ggrossetie]

I think we can close this issue, the "Installing and Using Asciidoctor.js" is now maintain in the Asciidoctor.js repository: https://github.com/asciidoctor/asciidoctor.js/blob/master/docs/modules/setup/pages and will be available on the future documentation site: https://github.com/asciidoctor/docs.asciidoctor.org

[mojavelinux]

And even now, the project page syncs with the README of the upstream project.

https://asciidoctor.org/docs/asciidoctor.js/

[ggrossetie]

I forgot about that, it's really nice :+1: