Building websites with Asciidoctor

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

Building websites with Asciidoctor

t00m
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:

--
Best regards,
Tomás Vírseda

--
Best regards

t00m

Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

rwinch
Thanks for sharing. Have you seen https://antora.org/ yet? It provides an elegant way of doing documentation websites with Asciidoctor.
Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

t00m
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

--
Best regards

t00m

Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

abelsromero
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!
Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

ciampix
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

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

Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

t00m
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

Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

t00m
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

Reply | Threaded
Open this post in threaded view
|

Re: Building websites with Asciidoctor

mojavelinux
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