Asciidoctor :: Discussion

Building websites with Asciidoctor

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

8 messages Options

t00m

Sep 07, 2018; 3:42pm

Building websites with Asciidoctor

HI there,

I am new in the list and also new with Asciidoctor (I discovered it 3 months ago).

I know that building a browsable documentation repository is not the final purpose of Asciidoctor. Doing some research, I found a post[1] talking about this topic but I couldn't find any script or application that convert a bunch of asciidoc documents into a website.

So I came up with my own solution . You can check the code here [2] and read some thoughts here [3].

I want to share it with you all. Maybe someone finds it useful.

Sure it is not the best way of achieving my goal so I accept any advise you can give me.

By the way, thanks to all creators and contributors of this wonderful project, Asciidoctor.

Refs:

[1] http://tomswan.com/blog/posts/2015-07-10-menus-in-asciidoc.html

[2] https://subversion.t00mlabs.net/listing.php?repname=KB4IT

[3] http://blog.t00mlabs.net/2018/09/06/new-kb4it-released/

Best regards,

Tomás Vírseda

t00mlabs.net

--
Best regards

t00m

rwinch

Sep 07, 2018; 3:45pm

Re: Building websites with Asciidoctor

Thanks for sharing. Have you seen https://antora.org/ yet? It provides an elegant way of doing documentation websites with Asciidoctor.

t00m

Sep 07, 2018; 3:59pm

Re: Building websites with Asciidoctor

Hi,

I didn't know about this project. I'll take a look in the coming days.

Thank you!

On Fri, Sep 7, 2018 at 5:45 PM rwinch [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks for sharing. Have you seen https://antora.org/ yet? It provides an elegant way of doing documentation websites with Asciidoctor.

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Building-websites-with-Asciidoctor-tp6461p6462.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Best regards,

Tomás Vírseda

t00mlabs.net

--
Best regards

t00m

abelsromero

Sep 07, 2018; 5:16pm

Re: Building websites with Asciidoctor

Welcome!

Keep in mind asciidoctor ecosystem is build on layers. Asciidoctor itself is focused on single-document rendering and leaves to other the fancy stuff like: index generation, multiple file conversion, HTML embedding, styling, etc.

* If you want a quick way to build a documentation repository, Antora is the way to go. Not only does the job mentioned above but enforces some really good practices in how to organise your docs and resources.

* If you want to build a customized static site, you can check how the asciidoctor and antora's sites are build:
- https://github.com/asciidoctor/asciidoctor.org
- https://gitlab.com/antora/antora.org
This will require some HTML/CSS work, but is not hard. I myself use this for my current project site :) Just used the antora site as a template, changed the CSS and reorganised a few things in a few days.

* If you are thinking about a blogging platform, you can check things like jbake, jekyll or https://github.com/HubPress/hubpress.io.

Also, i found some old posts in the forum, maybe they help: http://discuss.asciidoctor.org/Use-AsciiDoctor-only-for-a-simple-website-td3681.html.
btw, this is not a RTFM :) I am aware the forum is not easy to search.

have fun!

ciampix

Sep 07, 2018; 5:19pm

Re: Building websites with Asciidoctor

In reply to this post by t00m

On Fri, Sep 07, 2018 at 08:59:30AM -0700, t00m [via Asciidoctor :: Discussion] wrote:
>
>
> Hi,
>
> I didn't know about this project. I'll take a look in the coming days.

You can use Hugo...

https://gohugo.io/
https://gohugo.io/content-management/formats/
https://discourse.gohugo.io/t/asciidoc-hugo-performance/10637/3

The KiCad website is made with Hugo: http://kicad-pcb.org/

--

Marco Ciampa

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

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

GNU/Linux User #78271
FSFE fellow #364

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

t00m

Sep 13, 2018; 8:17pm

Re: Building websites with Asciidoctor

Hi there,

thanks for letting me know this project. I've put it in my wish list :)

--
Best regards,
Tomás Vírseda
t00mlabs.net

--
Best regards

t00m

t00m

Sep 13, 2018; 8:41pm

Re: Building websites with Asciidoctor

In reply to this post by abelsromero

Hi,

thanks for your explanation. It is quite interesting how can be integrated with a git repository. I'll read more about it and I'll try to test it. However, for me, is more than what I need. But I think it could be useful inside a company.

I'm not a blogger but a system administrator. The only that I want is to write down small notes and procedures very quickly. Also, I'm quite happy with my script because I can use as many custom properties as I want and I can display the info in the way that I want. Also, for me is important not to spend too much time installing and configuring stuff. I just wanted an all-in-one script (download, execute and display)

Of course, without having read nor tested other solutions (like Hugo or Antora) maybe I am wasting my time :)

Anyway, I am glad knowing that there are more options and people working in this topic.

Thanks everybody for your comments.

I have fun for the rest of the year ;-)

--
Best regards,
Tomás Vírseda
t00mlabs.net

--
Best regards

t00m

mojavelinux

Oct 09, 2018; 11:47pm

Re: Building websites with Asciidoctor

Administrator

In reply to this post by abelsromero

Excellent summary Abel! Thanks for putting that together.

-Dan

On Fri, Sep 7, 2018, 11:16 abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Welcome!

Keep in mind asciidoctor ecosystem is build on layers. Asciidoctor itself is focused on single-document rendering and leaves to other the fancy stuff like: index generation, multiple file conversion, HTML embedding, styling, etc.

* If you want a quick way to build a documentation repository, Antora is the way to go. Not only does the job mentioned above but enforces some really good practices in how to organise your docs and resources.

* If you want to build a customized static site, you can check how the asciidoctor and antora's sites are build:
- https://github.com/asciidoctor/asciidoctor.org
- https://gitlab.com/antora/antora.org
This will require some HTML/CSS work, but is not hard. I myself use this for my current project site :) Just used the antora site as a template, changed the CSS and reorganised a few things in a few days.

* If you are thinking about a blogging platform, you can check things like jbake, jekyll or https://github.com/HubPress/hubpress.io.

Also, i found some old posts in the forum, maybe they help: http://discuss.asciidoctor.org/Use-AsciiDoctor-only-for-a-simple-website-td3681.html.
btw, this is not a RTFM :) I am aware the forum is not easy to search.

have fun!

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Building-websites-with-Asciidoctor-tp6461p6464.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]