Use AsciiDoctor only for a simple website
Locked
 
|
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 |
Re: Use AsciiDoctor only for a simple website
|
|
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. |
|
|
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 |
|
This post was updated on .
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
|
|
|
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 |
|
This post was updated on .
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! |
|
|
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
|
|
|
Have a look at https://github.com/nerk/asciidoctor-bs-themes
|
|
|
That seem like what I'm looking for. Thanks again!
- Ted
@TedAtCIS
|
|
|
You are welcome. Still I would like to know your opinion about asciidocular.
|
Re: Use AsciiDoctor only for a simple website
Administrator
|
In reply to this post by suy
On Mon, Aug 17, 2015 at 12:11 AM, suy [via Asciidoctor :: Discussion] <[hidden email]> wrote:
+1 My bet exactly ;) |
Re: Use AsciiDoctor only for a simple website
|
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, |
Re: Use AsciiDoctor only for a simple website
|
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:
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen |
|
|
This post was updated on .
In reply to this post by mojavelinux
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
|
«
Return to Asciidoctor :: Discussion
|
1 view|%1 views
| Free forum by Nabble | Edit this page |