Login  Register

Use AsciiDoctor only for a simple website

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
14 messages Options Options
Embed post
Permalink
suy
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Use AsciiDoctor only for a simple website

suy
Hello.

I have an old web site running on top of MediaWiki. I never used the
collaboration aspect of the wiki, I only wanted the simple markup experience
and little else. As you'll probably imagine, I am considering migrating it all
to AsciiDoctor.

I know stuff like Gollum, Middleman or Awestruct exist, but after trying some
of them, or just reading the workflow they impose, I didn't like them much. I
understand that for having a sitemap, an RSS/Atom feed for news/blog, etc.,
you are likely going to need a lot of manual work if you don't use a site
generator, but still I don't see much value in them.

I'd like to have your input on this, though. AsciiDoctor alone has some nice
features to customize adding content to the footer, where I could add some
HTML to have a shared side bar on all pages, etc. Or I could just post process
the output with an AsciiDoctor plugin, or after the HTML is in disk using
Nokogiri or similar.

Do you have an opinion for or against something like this?

Thank you!

--
Alex (a.k.a. suy) | GPG ID 0x0B8B0BC2
http://barnacity.net/ | http://disperso.net
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

johncarl81
Alex,

We have two projects that might be of interest for you.

First, if you're interested in a blogging platform, Hubpress (https://github.com/HubPress/hubpress.io) gives you the ability to write your blog in Asciidoc syntax (it uses Asciidoctor under the covers) and host on Github.  I haven't used Hubpress much, but I've heard that it's a breeze.

Second, if you're looking for more of a website we have the JAQ (https://github.com/asciidoctor/jekyll-asciidoc-quickstart) project that gives you a leg-up in developing a site centered around Asciidoc content.  JAQ uses the Jekyll-asciidoc ruby library to leverage github pages and Travis to automatically process and host your content.  This means you can edit your Asciidoc content on Github directly and the infrastructure will process and deploy your website.  I use this on my project websites:  http://parceler.org and http://androidtransfuse.org ... here's the source for each respecitively: https://github.com/johncarl81/parceler-site and https://github.com/johncarl81/transfuse-site .

I've also seen websites based on Awestruct (I believe the asciidoctor.org website is) but I haven't focused on it as a solution.

I'm interested to hear if either of these options meets your requirements.

John



On Sun, Aug 16, 2015 at 10:43 AM, suy [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hello.

I have an old web site running on top of MediaWiki. I never used the
collaboration aspect of the wiki, I only wanted the simple markup experience
and little else. As you'll probably imagine, I am considering migrating it all
to AsciiDoctor.

I know stuff like Gollum, Middleman or Awestruct exist, but after trying some
of them, or just reading the workflow they impose, I didn't like them much. I
understand that for having a sitemap, an RSS/Atom feed for news/blog, etc.,
you are likely going to need a lot of manual work if you don't use a site
generator, but still I don't see much value in them.

I'd like to have your input on this, though. AsciiDoctor alone has some nice
features to customize adding content to the footer, where I could add some
HTML to have a shared side bar on all pages, etc. Or I could just post process
the output with an AsciiDoctor plugin, or after the HTML is in disk using
Nokogiri or similar.

Do you have an opinion for or against something like this?

Thank you!

--
Alex (a.k.a. suy) | GPG ID 0x0B8B0BC2
http://barnacity.net/ | http://disperso.net



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

suy
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

suy
El Monday 17 August 2015, johncarl81 [via Asciidoctor :: Discussion] escribió:
> I've also seen websites based on Awestruct (I believe the asciidoctor.org
> website is) but I haven't focused on it as a solution.
>
> I'm interested to hear if either of these options meets your requirements.

Thank you for your reply. Yes, I was aware of all of this options, but I'm
looking into something different. I had some experiences with solutions like
this, and it doesn't go well with me (maybe I'm too picky, sorry). :-/

I tried awestruct yesterday, but it failed both at build and "development"
mode. Jekyll causes me a lot of rejection because it is the first place where
I saw markdown plus the YAML frontmatter, something that I highly dislike (I'm
betting on AsciiDoc because I see it as an extensible document format where I
can add metadata in the same language of the data, like I can do with HTML). I
saw MiddleMan as an alternative that might have better documentation and
community, and a while ago I started using it for something different, but I
found lack of documentation and support when I needed to add content to the
metadata to bypass the frontmatter, a bit like jekyll-asciidoc does. I *was*
able to do it, but I had no feedback on wether that was using internals and
could break.

AsciiDoctor already does the conversion to HTML, and in the process it can do
it with some nice features to control other parts of the contents, so I'm
inclined to give a try to that approach first. That's why it surpises me that
everyone seems to need a complex site generator to do it. Maybe I'm missing
something and I don't see what.

Thank you again.

--
Alex (a.k.a. suy) | GPG ID 0x0B8B0BC2
http://barnacity.net/ | http://disperso.net
Ted
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

Ted
This post was updated on Aug 17, 2015; 5:52pm.
You don't need a complex generator to make a website with Asciidoctor.

You could create your content in AsciiDoc. Include a header and footer file. Use Smart Links to convert links from pageTwo.adoc to pageTwo.html (see http://discuss.asciidoctor.org/Link-to-an-other-document-td2857.html)

Then just run each content page through Asciidoctor to produce your website.

So just for fun I've created a website using only Asciidoctor: http://tedbergeron.github.io/SiteMadeWithAsciidoctor/

You can see the files and how to do it using one command: https://github.com/tedbergeron/SiteMadeWithAsciidoctor

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

If you want a bit more, you'll want to look at using Static Website Generators.

I created a Grunt script that automates the process a bit https://github.com/tedbergeron/grunt-asciidoctor-assemble.

Basically it takes all your AsciiDoc files and renders them. Dumps them into an HTML template, like Bootstrap. By using a template, I don't bother with include header/footer .adoc because I am putting that content into the HTML.

I agree that creating websites with Asciidoctor is a great idea! But if the website has more than a few pages, then I'm probably going to use a Static Website Generator. For blogging I really like HubPress and I'm experimenting with Jekyll with Asciidoctor plugin for larger websites.

- Ted @TedAtCIS
suy
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

suy
El Monday 17 August 2015, escribió:

> You don't need a complex generator to make a website with Asciidoctor.
>
> You could create your content in AsciiDoc. Include a header and footer
> file. Use Smart Links to convert links from pageTwo.adoc to pageTwo.html
> (see http://discuss.asciidoctor.org/Link-to-an-other-document-td2857.html
> <http://discuss.asciidoctor.org/Link-to-an-other-document-td2857.html>  )
>
> Then just run *each content page* through Asciidoctor to produce your
> website.
>
> ... Which is why everyone wants to automate that process a little bit more
> using Static Website Generators.
>
> I created a Grunt script that automates the process a bit
> https://github.com/tedbergeron/grunt-asciidoctor-assemble
> <https://github.com/tedbergeron/grunt-asciidoctor-assemble>  .
>
> Basically it takes all your AsciiDoc files and renders them. Dumps them
> into an HTML template, like Bootstrap. By using a template, I don't bother
> with include header/footer .adoc because I am putting that content into
> the HTML.
>
> I agree that creating websites with Asciidoctor is a great idea! But if the
> website has more than a few pages, then I'm probably going to use a Static
> Website Generator. For blogging I really like HubPress and I'm
> experimenting with Jekyll with Asciidoctor plugin for larger websites.


Well, it's good to know that at least you don't consider it crazy. :)

I will attempt the manual approach, but I'll keep an eye on the other
solutions just in case.

Thank you!

--
Alex (a.k.a. suy) | GPG ID 0x0B8B0BC2
http://barnacity.net/ | http://disperso.net
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

RobWin
This post was updated on Oct 01, 2015; 3:45pm.
In reply to this post by suy
Have a look at https://github.com/RobWin/asciidocular.
I created it some days ago and its still a prerelease Version. Asciidocular is a small AngularJS web app that loads AsciiDoctor files via Ajax and renders them as a full web site. Asciidocular uses asciidoctor.js to convert the AsciiDoc files into HTML. Asciidocular can be used to create a documentation site of your project or API.

Advantages:

No server-side components like nodejs, Ruby or Java needed.

No build process and tools needed to convert your AsciiDoc files into HTML

Deployable via GitHub Pages

Responsive Bootswatch (Bootstrap) theme

Just create AsciiDoc files and deploy!
Ted
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

Ted
RobWin wrote
I will certainly try that!

Does anybody know if you could point to a template (like Bootstrap) and render a website with Asciidoctor from the command line?

like asciidoctor -T path/to/bootstrap/template *.adoc

I would like to put together a bunch of templates for people looking to 'publish' their docs as an HTML website.

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

Re: Use AsciiDoctor only for a simple website

RobWin
Ted
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

Ted
RobWin wrote
That seem like what I'm looking for. Thanks again!
- Ted @TedAtCIS
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

RobWin
You are welcome. Still I would like to know your opinion about asciidocular.
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

mojavelinux
Administrator
In reply to this post by suy

On Mon, Aug 17, 2015 at 12:11 AM, suy [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'm betting on AsciiDoc because I see it as an extensible document format where I
can add metadata in the same language of the data, like I can do with HTML

+1

My bet exactly ;)

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

mojavelinux
Administrator
In reply to this post by suy

On Tue, Aug 18, 2015 at 11:43 PM, suy [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Well, it's good to know that at least you don't consider it crazy. :)

I don't think it's a crazy idea either. However, Asciidoctor does need to be paired with at least a build script for this task, which is why a lot of people jump towards a static site generator.

Static site generators can be thought of as domain-specific builds, where the build domain is that of a website. But they also tend to include a lot of features that appeal to someone that doesn't want to do things by hand. If you do want to do things by hand, then I think the ideal solution for you to combine Asciidoctor with a build tool like Gulp, Grunt, Gradle or Rake. That way, you can automate the generation of each page (as Ted points out), but you can do it in the most minimal way possible.

I think it's important to recognize that Asciidoctor is a document converter, not a build tool. When combined with a build tool, you've got a powerful combination at the low-end side (tinkerer) of the spectrum.

I also tend to agree that the static site generators tend to be overly complex, or take you too far away from the source material. Awestruct especially, and Jekyll to a lesser degree, require a commitment to understand how they work (and how to work with them) because both require you to install a whole slew of gems and get used to using "development" mode. JBake definitely has a leg up here because it comes packaged all as one and runs on a JVM...but if you aren't into JVMs, then that can be an issue.

To each their own. There is no one right solution. We need to be mindful of that when we recommend tools to others.

Cheers,

-Dan

--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

mojavelinux
Administrator
In reply to this post by suy
Early today I discovered (or perhaps rediscovered) adocsite, which appears to be a minimal script around Asciidoctor to handle the concern Ted pointed out...just being able to run Asciidoctor on a bunch of files.


I haven't tried it, just pointing it out for further exploration.

Cheers,

-Dan

On Thu, Oct 1, 2015 at 1:47 PM, Dan Allen <[hidden email]> wrote:

On Tue, Aug 18, 2015 at 11:43 PM, suy [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Well, it's good to know that at least you don't consider it crazy. :)

I don't think it's a crazy idea either. However, Asciidoctor does need to be paired with at least a build script for this task, which is why a lot of people jump towards a static site generator.

Static site generators can be thought of as domain-specific builds, where the build domain is that of a website. But they also tend to include a lot of features that appeal to someone that doesn't want to do things by hand. If you do want to do things by hand, then I think the ideal solution for you to combine Asciidoctor with a build tool like Gulp, Grunt, Gradle or Rake. That way, you can automate the generation of each page (as Ted points out), but you can do it in the most minimal way possible.

I think it's important to recognize that Asciidoctor is a document converter, not a build tool. When combined with a build tool, you've got a powerful combination at the low-end side (tinkerer) of the spectrum.

I also tend to agree that the static site generators tend to be overly complex, or take you too far away from the source material. Awestruct especially, and Jekyll to a lesser degree, require a commitment to understand how they work (and how to work with them) because both require you to install a whole slew of gems and get used to using "development" mode. JBake definitely has a leg up here because it comes packaged all as one and runs on a JVM...but if you aren't into JVMs, then that can be an issue.

To each their own. There is no one right solution. We need to be mindful of that when we recommend tools to others.

Cheers,

-Dan

--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Ted
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Re: Use AsciiDoctor only for a simple website

Ted
This post was updated on Oct 03, 2015; 5:37pm.
In reply to this post by mojavelinux
mojavelinux wrote
I also tend to agree that the static site generators tend to be overly complex...

To each their own. There is no one right solution...
--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
I want to offer one more simple idea: custom templates that could be used as an option for the default Asciidoctor  HTML template.

This would be for Documentarians that just need a small website to share their docs.

In this example I have 4 AsciiDoc files that are linked together. I've created a Slim template that frames the output.
http://tedbergeron.github.io/AsciidoctorCustomTemplate/


You render all the docs at once to produce the mini-website with a command like this:

$ asciidoctor -T template/slim *.adoc


My thought is several different template designs could be made.
This would give people moving to Asciidoctor, more choices for easily rendering a website.

I consider HTML output to be the most important document output. Since it is easy to host and share world-wide. As opposed to .pdf, etc.

Here are my source files:
https://github.com/tedbergeron/AsciidoctorCustomTemplate

This is my first attempt at using Slim. The template could use a lot of work.

- Ted @TedAtCIS