Writing BLOG in Asciidoctor

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 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.
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

benibilme
Hello,

I have searching a viable platform to blog with asciidoc however I can cleary say that asciidoc is not a first class citezen in anywhere. Jekyll seems to best support for it, not because of jekyll but because of well documented and well-maintained plugin. I wish a ruby implementation Jekyll did not use plugin for asciidoctor but it is so. Plugin means in general trouble.

I have switched to Hugo which seems to support asciidoc among other things, but there seems to be many gotches which must be eliminated.. There are some blogs which documents and partial solutions but they seem to be all hacks, not as clean as mardown solutions...

I asked help from this forum to create a documenation or tooling for Hugo.
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

David Jencks
I don’t really know anything about Hugo but there is yuzutech/blog.yuzutech.fr: Code, content and configuration for blog.yuzutech.fr which is a modification of Antora to produce a blog.  I’m working on turning that code into an Antora extension so you can have a “blog component” in an otherwise “normal” Antora site.  At the moment this is probably in the nature of an experiment but I think it shows promise.

David Jencks

On Mar 30, 2020, at 9:34 PM, benibilme [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hello,

I have searching a viable platform to blog with asciidoc however I can cleary say that asciidoc is not a first class citezen in anywhere. Jekyll seems to best support for it, not because of jekyll but because of well documented and well-maintained plugin. I wish a ruby implementation Jekyll did not use plugin for asciidoctor but it is so. Plugin means in general trouble.

I have switched to Hugo which seems to support asciidoc among other things, but there seems to be many gotches which must be eliminated.. There are some blogs which documents and partial solutions but they seem to be all hacks, not as clean as mardown solutions...

I asked help from this forum to create a documenation or tooling for Hugo.


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

Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

Patrick Ben Koetter
In reply to this post by blueray
* blueray [via Asciidoctor :: Discussion] <[hidden email]>:
>
>
> 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?

Speaking for myself only: I use pelican <https://blog.getpelican.com/> to
render AsciiDoc into a blog.

p@rick


--
[*] sys4 AG

https://sys4.de, +49 (89) 30 90 46 64
Schleißheimer Straße 26/MG,80333 München

Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263
Vorstand: Patrick Ben Koetter, Marc Schiffbauer, Wolfgang Stief
Aufsichtsratsvorsitzender: Florian Kirstein

Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

benibilme
Hello, as a matter of fact I have checked pelican before but the documentation does not state anything about asciidoc support, in addition in its support forum there was a question about it and the author asked if there is request make a issue about it...So I have thought that asciidoc is not being supported...How do you use it?
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

gour
In reply to this post by Patrick Ben Koetter
Patrick Ben Koetter wrote
Speaking for myself only: I use pelican <https://blog.getpelican.com/> to
render AsciiDoc into a blog.
Well, there is also plugin for Nikola which I find a bit more pleasant to use than Pelican...
Reply | Threaded
Open this post in threaded view
|

Re: Writing BLOG in Asciidoctor

Patrick Ben Koetter
In reply to this post by benibilme
* benibilme [via Asciidoctor :: Discussion] <[hidden email]>:
> Hello, as a matter of fact I have checked pelican before but the
> documentation does not state anything about asciidoc support, in addition in
> its support forum there was a question about it and the author asked if
> there is request make a issue about it...So I have thought that asciidoc is
> not being supported...How do you use it?

I'm using the
https://github.com/getpelican/pelican-plugins/tree/master/asciidoc_reader[asciidoc_reader]
plugin and I included it like this in pelicanconf.py:

PLUGINS = ["asciidoc_reader"]

Worked out of the box for me.

p@rick