Write a tutorial for how to blog with AsciiDoc and Awestruct

[mojavelinux]

Write a tutorial that covers how to write a blog entry in AsciiDoc for an Awestruct site*.

Here's a rough outline that identifies the scope of the tutorial:

• Motivation / vision (short and sweet)
  • Using a lightweight markup language makes it easy to focus on content and write
  • Preview on GitHub (don't need to build site just to see it)
  • Collaboration via pull requests
  • Can revise or even create directly online
• A brief section (or link to another tutorial) about setting up Awestruct to use as a blog
• Creating a new file for a blog entry
  • Where to put it (blog/ folder)
  • What to name it (file name becomes URL "slug")
  • What file extension to use (.ad is where we want to get, but .adoc is required for GitHub preview now)
• Blog entry header
  • Blog title
  • Author (can we set a default author?)
  • Date (soft date, will be updated by script)
  • Tags (:awestruct-tags: [tag1, tag2])
  • imagesdir: ../images (important for image preview on GitHub)
  • Draft (:awestruct-draft: true) to prevent automatic publishing
• Blog entry content
  • just AsciiDoc, refer to AsciiDoc Writer's Guide
  • put images in images/ folder, reference path relative to that folder (e.g. image:sky.jpg[])
• Publishing GitHub pages
  • Set timezone in _config/site.yml
  • Rakefile for setting date according to time-zone
  • Link to tutorial about automatic publishing of Awestruct site to GitHub pages via Travis CI
• Customizing AsciiDoc output using templates (perhaps not in first version)

* We may be able to update this tutorial in the future to include steps for using other static-site generation tools once they offer similar AsciiDoc integration to Awestruct.

[jaredmorgs]

I'm going through the backlog to try and get a sense of "next actions" in this repo.

How relevant is this post given the other SSGs like the Jekyll Asciidoc Quickstart, or HubPress?

[mojavelinux]

I still think this is relevant, but now I'm more inclined to write about Middleman than Awestruct. Having said that, the issue did predate JAQ and HubPress, so perhaps now it could help inform the structure of the documentation for those projects. I think the requirements here are still relevant for what a writer needs to know to master blogging with AsciiDoc. Let's label it as future.

[jagdeepjain]

@mojavelinux just checking if this is still open? And this has to be done with Middleman?