Easier Documentation, Simpler Websites & Faster Collaboration

$ ruby --version
# ruby 1.9.3p848 (2013-11-22 revision 40747) [x86_64-linux]

$ rvm use 2.0.0@writeadapt --create

$ gem install tilt --version 1.4.1
$ gem install awestruct --version 0.5.4.rc3
$ gem install asciidoctor

$ awestruct --version

$ mkdir writeadapt

$ cd writeadapt

$ awestruct -i -f foundation

$ cat > Gemfile << LINES
source 'https://rubygems.org'
gem 'awestruct', '0.5.4.rc3'
gem 'asciidoctor', '0.1.4'
gem 'tilt', '1.4.1'
gem 'rake', '>= 0.9.2'
gem 'git', '1.2.6'
LINES

$ gem install bundler
$ bundle install

$ rake

$ git init .

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

$ touch .nojekyll

$ echo "" > .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 preview

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

= About {sitename} (1)
Your Name
:page-layout: base (2)
:showtitle: (3)

[.lead]
{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

.paragraph.lead > p {
  @extend %lead;
}

$ 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 .nojekyll
$ git commit -m "Seed publish branch for GitHub Pages"

$ git push origin gh-pages
$ git checkout master

http://%USERNAME%.github.io/writeadapt-%USERNAME%

profiles:
  development:
    deploy: nil (1)
  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: http://%USERNAME%.github.io/writeadapt-%USERNAME%/images (2)
    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

http://%USERNAME%.github.io/writeadapt-%USERNAME%

**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
:page-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

:excerpt: Excerpt of post.
:page-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

# append
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