Using asciidoctor to create a website/blog

914 views
Skip to first unread message

Fernando Basso

unread,
Mar 29, 2016, 10:58:29 AM3/29/16
to asciidoc
I am pondering the use of Asciidoctor to create a website for myself, where I write about programming and other things that interest me. Can Asciidoctor be used for something like that? How easy/hard it would be to add a custom column to the pages, header (navigation), footer, etc? I know my question is probably to broad, but any insight is appreciated.

I took a look at the source for asciidoctor.org but could not understand much so far. For instance, how is the right column on the main page inserted?

Thanks in advance for any help.

Marco Ciampa

unread,
Mar 29, 2016, 3:10:44 PM3/29/16
to asci...@googlegroups.com
The KiCad site is done using asciidoc(tor) + hugo.

https://github.com/KiCad/kicad-website

bye

--


Marco Ciampa

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

+------------------------+
| GNU/Linux User #78271 |
| FSFE fellow #364 |
+------------------------+

Fernando Basso

unread,
Mar 29, 2016, 6:39:03 PM3/29/16
to asciidoc
Thanks. I will take a look. I am also trying jekyll-asciidoc.

Tom Swan

unread,
Mar 30, 2016, 9:05:48 AM3/30/16
to asciidoc
I recently rewrote my web site www.tomswan.com using almost entirely Asciidoctor with very little hand HTML coding and no other 3rd party platforms. A lot of the .adoc source code will be available for download as soon as I can complete my Asciidoc tutorial as promised on the Programming page. -- Tom

Charles Reynolds

unread,
Jan 3, 2017, 11:31:59 PM1/3/17
to asciidoc


On Wednesday, March 30, 2016 at 5:05:48 AM UTC-8, Tom Swan wrote:
I recently rewrote my web site www.tomswan.com using almost entirely Asciidoctor with very little hand HTML coding and no other 3rd party platforms. A lot of the .adoc source code will be available for download as soon as I can complete my Asciidoc tutorial as promised on the Programming page. -- Tom

Bump.

Tom, have you any update on this? I'm of a strong mind to do this myself. Asciidoctor contains (almost) everything I need in a static site builder. Everything but a blog engine and commenting, that is. I'm pretty sure everything else can be done pretty much with just asciidoctor.

Dan Allen

unread,
Jan 4, 2017, 2:03:55 AM1/4/17
to asci...@googlegroups.com
Why not use the Jekyll AsciiDoc plugin? There's good AsciiDoc support in several static site generators, but clearly the ecosystem for Jekyll is the largest.


(If you can figure it out, I recommend using master as it has numerous improvements that are yet unreleased. I need to get another release out soon).

Cheers,

-Dan

--
You received this message because you are subscribed to the Google Groups "asciidoc" group.
To unsubscribe from this group and stop receiving emails from it, send an email to asciidoc+unsubscribe@googlegroups.com.
To post to this group, send email to asci...@googlegroups.com.
Visit this group at https://groups.google.com/group/asciidoc.
For more options, visit https://groups.google.com/d/optout.



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

Paraplegic Racehorse

unread,
Jan 4, 2017, 2:15:29 AM1/4/17
to asci...@googlegroups.com
On Tue, Jan 3, 2017 at 10:03 PM, Dan Allen <dan.j...@gmail.com> wrote:
> Why not use the Jekyll AsciiDoc plugin?


Two words, and it applies to pretty much all of the programmatic
static site builders: arcane theming. I looked into Jekyll and Nikola
and a few others and the theming stuff was just terrible, particularly
if I'm writing in Asciidoc. Any given page's structure is already
created once passed through asciidoctor. Why, then, also pass it all
through an HTML template and some horridly documented CSS theme
engine?

Also, none of them support (well) a static __site__ with a blog
section. They're all blogs first, which is not nearly as useful for my
purpose. Many make it terribly difficult to set a static landing page
instead of a blog index. All I need is six or eight static pages with
a small, rarely updated, blog section. I have thought about org-mode
for the blog section and asciidoc for everything else...

--
I'm Paraplegic Racehorse.
"Grand Curmudgeon" :: International Discordance of Kilted Apiarists, Local #994.
http://www.paraplegicracehorse.net/

Dan Allen

unread,
Jan 4, 2017, 4:37:38 AM1/4/17
to asci...@googlegroups.com

On Wed, Jan 4, 2017 at 12:15 AM, Paraplegic Racehorse <paraplegic...@gmail.com> wrote:
Why, then, also pass it all
through an HTML template and some horridly documented CSS theme
engine?

The Jekyll AsciiDoc plugin supports generating standalone HTML documents generated by Asciidoctor. But it adds the benefit of being able to manage other pages, assets (like images), and publish. There are certainly other static site generators that do it better, but the Jekyll AsciiDoc plugin provides a template for behavior.

-Dan

Dan Allen

unread,
Jan 4, 2017, 4:39:47 AM1/4/17
to asci...@googlegroups.com
On Wed, Jan 4, 2017 at 12:15 AM, Paraplegic Racehorse <paraplegic...@gmail.com> wrote:
none of them support (well) a static __site__ with a blog
section. They're all blogs first, which is not nearly as useful for my
purpose.

This changed in Jekyll 3. It's now a static site first, blog as an add on (as it supports collections). Trust me, Jekyll has issues. But that team is definitely working hard to evolve it.

-Dan

Tom Swan

unread,
Jan 4, 2017, 11:52:26 AM1/4/17
to asciidoc
I'm still working on it and wondering how best to share the information. Right now I have nearly completed a working development system -- a series of templates and scripts -- that when cloned can be used to create a full web site using only Asciidoctor as the HTML generator and Asciidoctor-pdf for PDF output. A series of shell scripts automates build and publication details to a localhost intranet or to a public internet web site. Themes and css styles are easily managed and selected, and I use the Asciidoctor stylesheet factory styles by default. My site (tomswan.com) is an example product and all pages and articles are written using Asciidoctor and my scripts. I am also using the system to publish my own intranet so I have easy access to my notes and other documents in my office and studio using Dropbox as a cloud go-between for file sharing.

Jekyll and Sphinx are both great pieces of software. If I were a web developer, I would consider using either or both. But I'm not. I'm a writer and a musician, and my system is tailored to be a _writer's_ system, not necessarily a programmer's. Only Asciidoctor, Asciidoctor-pdf and a text editor are required (I use Sublime Text 3).  My goal is to have a system that I can use to write articles, code examples (mia is a very early example), book-length manuscripts, and annotated musical scores to accompany my instructional videos as in this article.

Because of the great and capable asciidoctor-pdf program, all of my articles on the site are published in HTML and  PDF formats. I don't have to create separate documents for downloading -- the _same_ text generates HTML and PDF outputs. ZIP file creation is also sensibly (I think) designed so that I can write an article, build it, and a ZIP file with examples is created for readers to download. I am exploring epub3 now as a book generator, but products are currently limited to articles and web sites.

I considered publishing the system on my own site, but I rejected this for several reasons. One, the programming is evolving rapidly. Two, this is early-stage material, _not_ robust, _not_ thoroughly tested, _strictly DIY!_ If there is enough interest, I'll create a Github package for it and release all files as open source. There are many many kludges -- hand written make files and the like that could and should be automatically generated. Working title is currently "Web Writer 2.0."

I agree that a blog package of some kind is essential, and here is where my code is sorely lacking. My own Blog isn't really a blog, I eventually realized, but more of a list of articles on various subjects. Nothing wrong with that, I guess, but I would like to make it a real blog eventually. What would you and others like to have in such a design?

Comments welcome. Thanks.
-- Tom

Paraplegic Racehorse

unread,
Jan 4, 2017, 1:22:49 PM1/4/17
to asci...@googlegroups.com
On Wed, Jan 4, 2017 at 7:52 AM, Tom Swan <t...@tomswan.com> wrote:
> I'm a writer and a musician, and my system is tailored to be a _writer's_
> system, not necessarily a programmer's. Only Asciidoctor, Asciidoctor-pdf
> and a text editor are required (I use Sublime Text 3). My goal is to have a
> system that I can use to write articles, code examples (mia is a very early
> example), book-length manuscripts,


and that is precisely what I want.

I haven't played with stylefactory, mostly because of Compass/SASS
junk. Atom has a really cool plugin to extract style-able elements
from an HTML document and create a CSS file for me, which I can then
modify to my liking. Brackets lets me do that with live reload and
makes media queries for responsive design (relatively) easy.

I have been talking a little with Jared Henley about updating
http://jared.henley.id.au/software/awb/[AsciiDoc Website Builder]. It
has a similar kludgey template system to other static site builders,
though, so I'm not convinced it's the right way to go for me. The
documentation is somewhat lacking, as well; which is to say, while
attempting to set up a basic test site, I ran into several questions
not answered in the docs.

Essentially, I want the hardest part of my site building to be
creating content. OK, initially, styling will be a bit of a bear. That
might take me a week to get it right. I can live with that. Dealing
with all the multiple templates and CSS files is a big part of why I
got away from WordPress. It's horrible; and every static sitebuilder
uses the same model. What a nightmare. No thanks. Not for me.

Also, I write wherever I happen to be. That often means I'm writing on
my phone - yes, awkward, but it puts words in a file for later
editing. I need to be able to arbitrarily create a new file and not
muck around with <sitebuilder> -newpage <title> because I simply can't
do it from there. Dropbox handles change propagation between devices.
It also handles (limited) version control but since I'll be publishing
with GitLab pages, real versioning will take place via Git.
Reply all
Reply to author
Forward
0 new messages