Writing BLOG in Asciidoctor

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

Writing BLOG in Asciidoctor

blueray
I am planning to start a blog. Most of my contents are in adoc format. I am planning a solution which support adoc format.

I searched the net. It talks about Hugo. Is it something the community recommends or is there a better solution?

Should I use asciidoctor stylesheet factory to render the articles according to my theme?

I need a custom header, footer and sidebar. Can I render the Asciidoctor file inside a div? What is the way to go here?
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

abelsromero
Welcome :)

I don't claim to be an expert, but the key questions for me is, ¿which environment do you feel more comfortable with?

* Java -> JBake. Easily installed with sdkman and uses asciidoctor as first class citizen, unlike others that use markdown. This means all styles should work perfectly.
* Ruby -> Jekyll or Middleman. It can all be installed using normal "gem" command, and you can use the versions with "bundler" to better control the versions you use. I've used it and the live preview features are really good. Just google and you will find some examples and templates ready to use.
* You don't care -> Hugo or any of the others. Hugo got a attraction for its OOTB lightness & speed, but in the case of asciidoctor, it just calls the asciidoctor gem in a separated process. So you don't get the full Hugo power and you still need to install Ruby and the required gems manually. The good thing is that there are many templates and styles to choose and since it uses the gems, you can use any extension and the latest asciidoctor version.  A good point is that Hugo documentation is really good and even includes video tutorials. I did a proof-of-concept some time ago and I could meet all my requirements and publish on gitlab using "google driven development".
* You'd like to get something quickly without much hassle -> https://github.com/HubPress/hubpress.io. It's an (imho) under-appreciated online solution. I see however it hasn't received recent updates, you'll be missing a few new features, but nothing critical.

In terms of complexity, they are more or less the same. They provide some template to inject headers, footers, menus, etc. and require you to define some asciidoc attributes to build the site. They convert AsciiDoc sources using the "--embedded" option so the HTML can be inserted in a div as you mention, then it uses the style css provided by each tool.

Can't comment on "asciidoctor stylesheet factory", sorry.
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

mojavelinux
Administrator
As Abel points out, there are many options available. Here's the list of the integrations off the top of my head:

* jekyll-asciidoc for integration with Jekyll
* built-in support in Hugo (as you mentioned)
* middleman-asciidoc for integration with Middleman
* built-in support in JBake
* built-in support in Nanoc
* HubPress.io for an AsciiDoc-based blog
* Awestruct as asciidoctor.org uses, though now defunct

(I'm sure there are others)

You can study opendevise.org as an example of using middleman-asciidoc to create an AsciiDoc-powered blog.


You can study the Jekyll AsciiDoc Quickstart as an example of using jekyll-asciidoc to create an AsciiDoc-powered site and blog.


You can also study https://developer.okta.com/blog/ as an example of using jekyll-asciidoc to create an AsciiDoc-powered site and blog.


You can study asciidoctor.org as an example of using Awestruct to create an AsciiDoc-powered site and blog (though no longer recommended).


> Should I use asciidoctor stylesheet factory to render the articles according to my theme?

I would recommend creating a new stylesheet for your site. You can use the one in https://github.com/asciidoctor/jekyll-asciidoc-quickstart as a starting point, or any of the other sites I mentioned. I don't recommend using the asciidoctor-stylesheet-factory as that is now only intended for use by Asciidoctor core to generate the default stylesheet. Otherwise, it's not maintained.

Best,

-Dan

--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

blueray
In reply to this post by abelsromero
Thank you (both) very much for this detailed and kind reply.