Asciidoctor CMS publisher

classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

Asciidoctor CMS publisher

mojavelinux
Administrator
While in France, I had several discussions with Guillaume Scheibel, creator of the Asciidoctor Confluence plugin {1}, about refactoring the Asciidoctor Confluence plugin into a pluggable CMS publishing tool. This would allow us to support additional CMS platforms and maximize code reuse.

Regardless of what we feel about them, CMS platforms are integral to many businesses. If we treat these systems as a publishing endpoint, it means authors can still write and maintain the content in AsciiDoc. Fortunately, most of these systems provide a publishing API that we can used to push generated HTML content produced by Asciidoctor. Rather than reinventing the wheel for every CMS, we could create a reusable purpose publishing tool that provides a uniform interface and develop adapters that connect to each of the systems.

Several of the systems we have in mind include:

* Confluence (possibly multiple versions)
* WordPress
* Drupal
* etc

We should also think about what the best language is for this tool (the core part). Should it be Ruby? Java? We could, of course, allow adapters to be written in any language, especially if the core runs on the JVM.

As for the name, I'm thinking it should be called asciidoctor-cms-publisher.

Once the core is extracted from asciidoctor-conflunce, we can start to think about what features are common to the various CMS and how the adapter interface should look.

To get some ideas for requirements for WordPress publishing, you can see the script that Micheal Hunger put together to publish AsciiDoc posts to WordPress that were generated from Asciidoctor {2}.

I look forward to hearing your ideas. If you are interested in this project, please get in touch with Guillaume.

Cheers,

-Dan

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

LightGuardjp
Administrator
I would think a JavaScript core would be good, or at least something that's easy to read and port. I know on the JVM you can run JavaScript, you can do the same on Ruby using therubyracer. PHP also has a v8 extension {1} that has been available since PHP 5.3.3. We all know how ubiquitous JavaScript has become, seems like the easiest choice to make it available to run everywhere.

:1: http://php.net/manual/en/book.v8js.php

On Thu, Apr 23, 2015 at 7:50 PM, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:
While in France, I had several discussions with Guillaume Scheibel, creator of the Asciidoctor Confluence plugin {1}, about refactoring the Asciidoctor Confluence plugin into a pluggable CMS publishing tool. This would allow us to support additional CMS platforms and maximize code reuse.

Regardless of what we feel about them, CMS platforms are integral to many businesses. If we treat these systems as a publishing endpoint, it means authors can still write and maintain the content in AsciiDoc. Fortunately, most of these systems provide a publishing API that we can used to push generated HTML content produced by Asciidoctor. Rather than reinventing the wheel for every CMS, we could create a reusable purpose publishing tool that provides a uniform interface and develop adapters that connect to each of the systems.

Several of the systems we have in mind include:

* Confluence (possibly multiple versions)
* WordPress
* Drupal
* etc

We should also think about what the best language is for this tool (the core part). Should it be Ruby? Java? We could, of course, allow adapters to be written in any language, especially if the core runs on the JVM.

As for the name, I'm thinking it should be called asciidoctor-cms-publisher.

Once the core is extracted from asciidoctor-conflunce, we can start to think about what features are common to the various CMS and how the adapter interface should look.

To get some ideas for requirements for WordPress publishing, you can see the script that Micheal Hunger put together to publish AsciiDoc posts to WordPress that were generated from Asciidoctor {2}.

I look forward to hearing your ideas. If you are interested in this project, please get in touch with Guillaume.

Cheers,

-Dan




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoctor-CMS-publisher-tp3022.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Ted
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

Ted
I'm very interested in this topic. I would second the vote to stick with JavaScript, since it would plug into any web-based CMS.

It would be useful if the asciidoctor-cms-publisher could deal with AsciiDoc files from any source like database or even text files in a repository.

I guess it would depend on the CMS that you are hooking into that would determine at what point asciidoctor-cms-publisher would render the HTML output.

One of the difficulties I had integrating Asciidoctor into a web app was getting the HTML classes it generated to play nice with the existing site styles. I ended up changing the asciidoctor.css so that it would only affect the content generated in its own <div>
- Ted @TedAtCIS
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

Guillaume
Hello,

That's really interesting, when I discussed about asciidoctor publisher (btw isn't the "CMS" too restrictive ?) I never thought about moving to another language (currently Ruby). But I think this kind of question is bigger than just asciidoctor-publisher, we could have the same about asciidoctor-core.
The question is then do we want to have a standard core (in for instance ruby) and then multiple wrapper in other languages ? Or do we want an abstract definition (a spec) of the core with N implementations (Java, JS, Ruby, ...) ?
But that's another topic (my vote goes for option #2 btw).

Back to the main topic, at first I would tend to stay in ruby to have the benefit from the existing code, the advantages of the asciidoctor ruby API and the CLI.  I don't know much about the extension capabilities of the JS implementation but  we will have to create 2 things per target:
- the target API caller implementation
- a converter, even if most of the time we're going to use the HTML backend the HTML produced is not exactly the one expected by the target (as Ted mentioned)

About the JS implementation, except using it in NodeJS, I don't really see the benefits probably because for me (at the point) this gem is only about using an API from an existing instance (server) via the CLI (or a script).

But I'm definitely opened let me know what you think.

Cheers,
Guillaume
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

mojavelinux
Administrator
In reply to this post by Ted
On Fri, Apr 24, 2015 at 2:32 PM, Ted [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'm very interested in this topic. I would second the vote to stick with JavaScript, since it would plug into any web-based CMS.

If we need it to be in JavaScript, then Ruby is still the clear choice since we can transpile Ruby to JavaScript and still be able to use it in Ruby (the opposite is not true).
 

It would be useful if the asciidoctor-cms-publisher could deal with AsciiDoc files from any source like database or even text files in a repository.

Great idea. I believe this came up when I was discussing it with Guillaume. Asciidoctor has to ability to render content from a string (or any IO object) so it should be very possible to work directly with streams.


One of the difficulties I had integrating Asciidoctor into a web app was getting the HTML classes it generated to play nice with the existing site styles. I ended up changing the asciidoctor.css so that it would only affect the content generated in its own <div>

We're going to handle this in a separate thread. There are historical reasons for the HTML output we have today, but it's time to start looking towards the future at something more semantic and easier to style.

-Dan

--
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

mojavelinux
Administrator
In reply to this post by Guillaume

On Sun, Apr 26, 2015 at 8:34 AM, Guillaume [via Asciidoctor :: Discussion] <[hidden email]> wrote:
(btw isn't the "CMS" too restrictive ?)

Good question. That was my gut instinct, but I suppose asciidoctor-publisher alone (without the CMS qualifier) is fitting.

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

mojavelinux
Administrator
In reply to this post by Guillaume

On Sun, Apr 26, 2015 at 8:34 AM, Guillaume [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Back to the main topic, at first I would tend to stay in ruby to have the benefit from the existing code, the advantages of the asciidoctor ruby API and the CLI.

..and we can still transpile to JavaScript from Ruby using Opal. While a native JavaScript implementation is tempting, we lose all the benefits you just identified of having a Ruby implementation.

I do agree that being able to run it from JavaScript is huge because we can integrate with any web-based front-end. For instance, HubPress is possible thanks to Asciidoctor.js. Asciidoctor Publisher (transpiled from Ruby) could fit in there as well.

Cheers,

Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

LightGuardjp
Administrator
I don't really care what its originally in as long as it can be transpiled to JavaScript and run in a JS runtime. 

On Monday, April 27, 2015, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

On Sun, Apr 26, 2015 at 8:34 AM, Guillaume [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Back to the main topic, at first I would tend to stay in ruby to have the benefit from the existing code, the advantages of the asciidoctor ruby API and the CLI.

..and we can still transpile to JavaScript from Ruby using Opal. While a native JavaScript implementation is tempting, we lose all the benefits you just identified of having a Ruby implementation.

I do agree that being able to run it from JavaScript is huge because we can integrate with any web-based front-end. For instance, HubPress is possible thanks to Asciidoctor.js. Asciidoctor Publisher (transpiled from Ruby) could fit in there as well.

Cheers,




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoctor-CMS-publisher-tp3022p3047.html
To start a new topic under Asciidoctor :: Discussion, email <a href="javascript:_e(%7B%7D,&#39;cvml&#39;,&#39;ml-node%2Bs49171n1h37@n6.nabble.com&#39;);" target="_blank">ml-node+s49171n1h37@...
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML


--

mac
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

mac
so ... any news on this topic?

Currently my team has fully adopted AsciiDoctor to create a project documentation. Usually developers/architects use standard text editor and render HTML using Blazej's fork of Chrome AsciDoc Preview plugin (https://github.com/bbucko/asciidoctor-chrome-extension) that supports PlantUML. Some others use Atom ...but in general we keep all .ad files in git. Then our CI (TeamCity) is generating documentation using asciidoc (Ruby) and publish to one of our webservers.

So far it works well ... however, at this stage we have a few new Team Members who:
1. Will never want to use git as they are not technical
2. Are used to wyswig type of editors. Atom could be good, but still #1 is a roadblock.

If there was a tool/app like CMS with AsciiDoc integrated we would address both issues.

Thus asking :)
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

simpligility

If you are going away from a git or other version controlled backend to a CMS you loose all the usefulness of pull requests, reviews, branches, merging and so on. I would suggest not to do that. 

Instead tell these non-technical users to either learn git with some frontend (e.g the github client or whatever) or get them to edit the files right in the browser as possible in github and others.

If these "non-technical" users can use an email program, a word processing tool or a presentation tool .. they can use git. No excuses.. 

manfred

mac [via Asciidoctor :: Discussion] wrote on 2016-09-28 14:12:

so ... any news on this topic?

Currently my team has fully adopted AsciiDoctor to create a project documentation. Usually developers/architects use standard text editor and render HTML using Blazej's fork of Chrome AsciDoc Preview plugin (https://github.com/bbucko/asciidoctor-chrome-extension) that supports PlantUML. Some others use Atom ...but in general we keep all .ad files in git. Then our CI (TeamCity) is generating documentation using asciidoc (Ruby) and publish to one of our webservers.

So far it works well ... however, at this stage we have a few new Team Members who:
1. Will never want to use git as they are not technical
2. Are used to wyswig type of editors. Atom could be good, but still #1 is a roadblock.

If there was a tool/app like CMS with AsciiDoc integrated we would address both issues.

Thus asking :)
 
If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Asciidoctor-CMS-publisher-tp3022p5018.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
Ted
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

Ted
This post was updated on .
In reply to this post by mac
mac wrote
So far it works well ... however, at this stage we have a few new Team Members who:
1. Will never want to use git as they are not technical
2. Are used to wyswig type of editors. Atom could be good, but still #1 is a roadblock.
I feel your pain. As far as I know there still isn't a WYSIWYG editor for Asciidoctor. So we need that. Then we need the reading and saving functions to hook to an interface.

Then write a couple classes. One that uses Git (let's just hook it to GitHub to show how it works). Another that hooks to mySQL for WordPress. Then a config that tells the interface if you are using GitHub or WordPress.

Then encourage other developers to write other connection classes for other popular apps. But all would have to fit into the interface for the  asciidoctor-publisher.

WYSIWYG editor for Asciidoctor Publisher


This Markdown editor has true WYSIWYG: https://github.com/bevacqua/woofmark but I like some of the features of this one: https://simplemde.com/. (Since Asciidoctor will render some Markdown, maybe this would just work? ... just kidding). How hard would it be to modify one of these editors to write Asciidoctor instead of Markdown? (famous last words) ;) edited

I like the way this one works because you could present the user with the WYSIWYG mode by default.
That way they would never need to learn Asciidoctor.

For most editing the user would only need the basics: italic, bold, headlines and bullet points. So don't bother adding more buttons to it ever. If the user needs to do anything beyond what the basic WYSIWYG buttons do, they will have to toggle to the text mode and learn to write Asciidoctor.

I also love how the SimpleMDE also expands into a side-by-side editor|viewer. Which seems to be how most Asciidoctor writers are used to working. And several people have already written things like this (https://asciidoclive.com/edit/scratch/1)


Repository Interface: Git and more


I like the idea of storing Asciidoctor as simple text files in the repo. That's what I've done, but I wasn't using Git :(

Use a trigger or button to fire a retrieve method into an API GET call to read the contents of the text file and dump that into your editor window. Use AsciidoctorJS to render it on the fly into the viewer window.

Then save the changes back via an API PUT call to update the text file which you could save on-change or use an old fashioned save button.

This completely removes the users need to know anything about Git.

If you were using a database for WordPress or a wiki, it shouldn't be that hard to swap out the SQL CRUD queries for API calls.


- Ted @TedAtCIS
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

ciampix
In reply to this post by mac
On Wed, Sep 28, 2016 at 02:12:56PM -0700, mac [via Asciidoctor :: Discussion] wrote:
>
>
> so ... any news on this topic?
>
[...]
>
> If there was a tool/app like CMS with AsciiDoc integrated we would address
> both issues.
>
> Thus asking :)

Search "drupal asciidoc" with your favorite search engine...

--


Marco Ciampa

I know a joke about UDP, but you might not get it.

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

 GNU/Linux User #78271
 FSFE fellow #364

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

mac
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

mac
In reply to this post by simpligility
The day Marketing and Analyst start using git will be the day we lose our jobs :)
Obviously I don't want to go away from git as my .ad sits next to the code so I can cross reference sources into documentation e.g.: pretty print xsd (btw ... the only thing that I find useful https://sourceforge.net/projects/xsdvi/ but it's kind of experiment rather than a project) and visualize jbpm processes (via https://github.com/bpmn-io/bpmn-js).

Now I'm thinking about having parallel wordpress (or other CMS) just for the purpouse of all git ignorants and then include their stuff into the main documentation via include macro ... however it's getting more complex than I want.

The reality of corporation is that you use what it gives you ... and we use Stash so as you may know it's not the best to edit files via web :)
mac
Reply | Threaded
Open this post in threaded view
|

Re: Asciidoctor CMS publisher

mac
In reply to this post by ciampix
will look for "drupal asciidoc" though

thx