Easier Documentation, Simpler Websites & Faster Collaboration

$ ruby --version
# ruby 1.9.3p429 (2013-05-15 revision 40747) [x86_64-linux]

$ curl -L https://get.rvm.io | bash -s stable --ruby=1.9.3

$ curl -L https://get.rvm.io | bash -s stable --ruby=1.9.3

$ rvm use 1.9.3@writeadapt --create

$ gem install awestruct

$ awestruct --version

$ mkdir writeadapt

$ cd writeadapt

$ awestruct -i -f foundation

$ gem install rake bundler

$ rake setup

$ rake

$ git init .

$ cat > .gitignore << LINES
/.awestruct/
/.ruby-*
/.sass-cache/
/_site/
/_tmp/
/Gemfile.lock
LINES

$ touch .nojekyll

$ git add .

$ git commit -m 'Initial import of website sources'

$ git remote add origin https://github.com/{username}/writeadapt-{username}
$ git push origin master

name: Write__Adapt__
title: WriteAdapt - For People Who Love Content
org: Strategy Media
author: The Octocat
author_url: https://github.com/octocat
base_url: ''
ctx_path: ''

# append
interpolate: false 1
haml:
  :ugly: true 2

$ rake clean
$ rake

gem 'asciidoctor', '>= 0.1.4.pre'

$ bundle install

# append
asciidoctor:
  :safe: safe
  :attributes:
    sitename: WriteAdapt
    base_url: ''
    ctx_path: ''
    idprefix: ''
    idseparator: '-'
    sectanchors: ''
    icons: font

= About {sitename} 1
Your Name
:awestruct-layout: base 2

{sitename} was founded by {author} during a conference workshop.
It's quickly becoming much bigger than this humble beginning.

This page is written in http://asciidoc.org[AsciiDoc].
It's transformed by http://awestruct.org[Awestruct] and http://asciidoctor.org[Asciidoctor] into a webpage for this static website.

        %li.divider
          %li
            %a(href="#{site.ctx_path}/about.html") About

$ rake clean preview

$ git submodule add -b embedded-stylesheets \
https://github.com/asciidoctor/asciidoctor-stylesheet-factory.git \
stylesheets/_themes

$row-width: 72em;
@import "_themes/sass/foundation-embedded.scss";

@import "foundation/components/buttons";
@import "foundation/components/button-groups";
@import "foundation/components/top-bar";
@import "foundation/components/inline-lists";
$pagination-link-unavailable-font-color: #e9e9e9;
@import "foundation/components/pagination";

$footer-bg: $body-font-color !default;
$footer-font-color: invert($body-font-color) !default;
.top-bar a {
  text-decoration: none;
}
h1 em {
  letter-spacing: 1px;
}
body > footer {
  background: $footer-bg;
  padding: $panel-padding;
  color: $footer-font-color;
}

require './stylesheets/_themes/lib/functions.rb'

$ rm stylesheets/{_normalize.scss,_settings.scss}

  #content.row
    .large-12.columns
      =content

.row
  .large-12.columns
    %h1 Welcome to #{Asciidoctor.render site.name, :doctype => :inline}!

      %li.name
        %h1
          %a(href="#{site.ctx_path}/")
            =Asciidoctor.render(site.name, :doctype => :inline)

$ rake clean preview

**bold**

*italic*

`literal`

`_posts`

*bold*

_italic_

+literal+ (or `literal`)

[path]+_posts+

---
layout: docs
title: Writing posts
prev_section: defining-frontmatter
next_section: creating-pages
permalink: /docs/writing-posts/
---

= Writing posts
:awestruct-layout: base
:showtitle:
:prev_section: defining-frontmatter
:next_section: creating-pages

## The Posts Folder

== The Posts Folder

<div class="note">
  <h5>ProTip™: Show line numbers</h5>
  <p>
    You can make code snippets include line-numbers by adding the word
    <code>linenos</code> to the end of the opening highlight tag like
    this: <code>{% raw %}{% highlight ruby linenos %}{% endraw %}</code>
  </p>
</div>

[TIP, caption='ProTip(TM)']
.Show line numbers
You can make code snippets include line-numbers by adding the word
`linenos` to the end of the opening highlight tag like this:
`{% raw %}{% highlight ruby linenos %}{% endraw %}`

[directory structure](../structure)

link:../structure[directory structure]

[Markdown](http://daringfireball.net/projects/markdown/)

http://daringfireball.net/projects/markdown[Markdown]

[get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/mydoc.pdf)

link:{ctx_path}/assets/mydoc.pdf[get the PDF]

As explained on the [directory structure](../structure) page, the `_posts`
folder is where your blog posts will live. These files can be either
[Markdown](http://daringfireball.net/projects/markdown/) or
[Textile](http://textile.sitemonks.com/) formatted text files, and as long as
they have [YAML front-matter](../frontmatter), they will be converted from their
source format into an HTML page that is part of your static site.

As explained on the link:../structure[directory structure] page, the `_posts`
folder is where your blog posts will live. These files can be either
http://daringfireball.net/projects/markdown/[Markdown] or
http://textile.sitemonks.com/[Textile] formatted text files, and as long as
they have link:../frontmatter[YAML front-matter], they will be converted from
their source format into an HTML page that is part of your static site.

![Helpful screenshot]({% raw %}{{ site.url }}{% endraw %}/assets/screenshot.jpg)

image::screenshots.jpg[Helpful screenshot]

One of Jekyll’s best aspects is that it is “blog aware”.

One of Jekyll's best aspects is that it is ``blog aware''.

{% highlight bash %}
YEAR-MONTH-DAY-title.MARKUP
{% endhighlight %}

[source,bash]
YEAR-MONTH-DAY-title.MARKUP

{% highlight ruby %}
def show
  @widget = Widget(params[:id])
  respond_to {|format| format.html # show.html.erb
  }
end
{% endhighlight %}

[source,ruby]
def show
  @widget = Widget(params[:id])
  respond_to {|format| format.html #<1>
  }
end

<1> show.html.erb

$ mkdir posts

Awestruct::Extensions::Pipeline.new do

  helper Awestruct::Extensions::Partial

  extension Awestruct::Extensions::Posts.new '/posts'

  extension Awestruct::Extensions::Paginator.new :posts, '/index',
      :page_name => 'posts/page/', :per_page => 5

  extension Awestruct::Extensions::Atomizer.new :posts, '/feed.xml',
      :num_entries => 10

end

$ mkdir _partials

- author_url = page.post.author_url || site.author_url
- post_url = "#{site.ctx_path}#{page.post.url}"
%article.post
  %header.post-head
    %h1.title
      %a{:href=>post_url}=page.post.title
    %h4
      %em by
      %a.author{:href=>author_url}
        %img(src="#{author_url}.png" width=24 height=24)
        =page.post.author || site.author
      on
      %time.pubdate{:datetime=>page.post.date.strftime('%FT%T%:z')}
        =page.post.date.strftime '%B %e, %Y'
  .post-body
    =page.post.content

---
layout: base
---
=partial 'post.html.haml', :post => page

- paginator = page.paginator
.pagination-centered
  %ul.pagination
    - if paginator.previous_page
      %li.arrow
        %a(href="#{site.ctx_path}#{paginator.previous_page.url}")
          %i.icon-step-backward
    - else
      %li.arrow.unavailable
        %a(href='#')
          %i.icon-step-backward
    %li #{paginator.current_page_index + 1} of #{paginator.pages.size}
    - if paginator.next_page
      %li.arrow
        %a(href="#{site.ctx_path}#{paginator.next_page.url}")
          %i.icon-step-forward
    - else
      %li.arrow.unavailable
        %a(href='#')
          %i.icon-step-forward

---
layout: base
---
.row
  .large-12.columns
    %h1 Welcome to #{Asciidoctor.render site.name, :doctype => :inline}!

.row
  .large-12.columns.posts
    - page.posts.each do |post|
      =partial 'post.html.haml', :post => post, :listing => true
    =partial 'pagination.html.haml', :paginator => page.posts

= Docs Workshop at OSCON 2013
Author Name
2013-07-22
:awestruct-tags: [conference, oscon]

Content of first post, reporting from OSCON!

%link(rel='alternate'
      type='application/atom+xml'
      href="#{site.ctx_path}/feed.xml")

$ rake clean preview

extension Awestruct::Extensions::Tagger.new :posts, '/index',
    'posts/tag', :per_page => 5

  %footer.post-footer
    - if page.post.tags
      .tags<
        %i.label.icon-tags
        -#=page.post.tag_links
        - page.post.tags.each_with_index do |tag, idx|
          - unless idx.zero?
            =', '
          %a{:href=>"#{site.ctx_path}#{tag.primary_page.url}"}=tag

$ rake clean preview

$ git commit . -m 'Enhancements'
$ git push origin master

$ git checkout --orphan gh-pages
$ rm -rf *
$ rm -rf .awestruct* .sass-* .gitignore .gitmodules
$ git rm --cached *
$ echo "GitHub Pages placeholder" > index.html
$ git add index.html
$ git commit -m "Seed publish branch for GitHub Pages"

$ git push origin gh-pages

$ git checkout master
$ git submodule update

profiles:
  development:
    deploy:
      dummy:
  production:
    base_url: http://{username}.github.io/writeadapt-{username}
    ctx_path: /writeadapt-{username}
    asciidoctor:
      :attributes:
        base_url: http://{username}.github.io/writeadapt-{username}
        ctx_path: /writeadapt-{username}
        # imagesdir must be absolute to work around Atom feed bug
        imagesdir: http://{username}.github.io/writeadapt-{username}/images
    deploy:
      host: github_pages
      branch: gh-pages

$ git commit _config/site.yml -m "Add profile for GitHub Pages deployment"
$ git push origin master

$ rake clean deploy

:excerpt: Excerpt of post.
:awestruct-excerpt: {excerpt}

{excerpt}

  .post-body
    - if page.listing
      %p=page.post.excerpt || summarize(html_to_text(page.post.content), 100)
      %p
        %a.small.secondary.button{:href=>post_url} Read more...
    - else
      =page.post.content

asciidoctor:
  :safe: safe
  :attributes:
    sitename: WriteAdapt
    base_url: ''
    ctx_path: ''
    idprefix: ''
    idseparator: '-'
    sectanchors: ''
    icons: font
    source-highlighter: coderay
    coderay-css: style

gem 'coderay'

$ bundle install

[source,ruby]
----
require 'asciidoctor'

puts Asciidoctor.render('Write__Adapt__', :doctype => :inline)
----

  #content.row
    .large-9.columns
      =content
    .large-3.columns
      - if page.source_path.end_with? '.adoc'
        - rel_path = page.relative_source_path
        %h4 Collaborate!
        %ul.button-group
          %li
            %a.small.button(href="#{site.edit_base_url}#{rel_path}")
              Edit
          %li
            %a.small.secondary.button(href="#{site.raw_base_url}#{rel_path}")
              Raw
          %li
            %a.small.secondary.button(href="#{site.log_base_url}#{rel_path}")
              Log
      %h4 Topics
      %ul.square
        - site.posts_tags.each do |tag|
          %li
            %a(href="#{site.ctx_path}#{tag.primary_page.url}")=tag

edit_base_url: https://github.com/{username}/writeadapt-{username}/edit/master
raw_base_url: https://github.com/{username}/writeadapt-{username}/raw/master
log_base_url: https://github.com/{username}/writeadapt-{username}/commits/master

$ rake clean preview