Merge pull request barryclark#8 from jaredmorgs/master

First Draft Edit

README.adoc

@@ -1,40 +1,111 @@
-= Jekyll Asciidoc Quickstart
+= Jekyll AsciiDoc Quickstart
+:toc:
 
-TODO
+== Congratulations!
 
-== Deploy site to GitHub Pages
+You've taken the first step down an easy path of blogging with Jekyll. Not only that, you've chosen AsciiDoc over Markdown which will give you fine control of the structure of your posts, and will make them display beautifully when you publish them using the default mobile-first stylesheets included in this repository.
 
-GitHub doesn’t (yet) whitelist the AsciiDoc plugin, so you can only run it on your own machine… or use a continuous integration platform like https://travis-ci.org/[Travis CI].
+== GitHub Pages and AsciiDoc
 
-You need two branches in your repository:
+GitHub Pages does not (yet) whitelist the jekyll-asciidoc plug-in, so you can not write `.adoc` posts and have them instantly publish like Markdown posts do.
 
-* **master** for markup sources and configuration (may be named differently),
-* **gh-pages** for generated static content (will be created automatically for you).
+Unlike some "fork and write" repositories that exist for Markdown blogs, you need to initially configure this repository fork with a computer to publish using AsciiDoc.
 
-The goal is to configure Travis CI job to listen for commits on the _master_ branch, automatically run jekyll build and push the generated content to the _gh-pages_ branch.
+=== How We Work Around The Limitation
+
+For this repository, the https://travis-ci.org/[Travis CI] Continuous Integration (CI) server emulates GitHub Pages staging automation, and pushes your blog live upon committing any change to the repository.
+
+After initially configuring the repository, you can use Git command-line on your computer, or even a Git client on your tablet or smartphone to write, commit, and automatically publish blog posts.
+
+=== Help Get AsciiDoc Whitelisted for GitHub Pages
+
+You can help change the lack of native AsciiDoc support by creating a support case through http://github.com/support.
+
+Tell the GitHub team that you want the choice to write in AsciiDoc, and have it handled the same way Markdown is when pushed to your GitHub Page.
+
+Your voice counts: make it heard!
+
+== Repository Structure
+
+The repository requires the following structure to work correctly:
+
+* **master**, for markup sources and configuration. This branch can be named anything you choose, however **master** is a general standard used in Jekyll blogs.
+* **gh-pages**, for the generated static content produced by Travis CI. This branch is the username.github.io GitHub Pages domain, which is created automatically for you when the Travis CI job runs.
+
+== Configuring the Repository for Publishing
+
+The goal of this procedure set is to configure a Travis CI job to listen for commits on the _master_ branch, automatically run the Jekyll build, and push the generated content to the _gh-pages_ branch.
+
+=== Install Minimum Jekyll Requirements
+
+You must install some software to execute commands in subsequent procedures. Meet the Requirements on the http://jekyllrb.com/docs/installation/[Jekyll Installation] page, which links to pages describing how to install:
+
+* ruby
+* rubygems
+
+For yum-based package managers, the command to run is:
+
+  $ sudo yum install ruby rubygems
+
+=== Install Travis Gem
+
+When you install rubygems, you can use the gem internal package management system to install the Travis CI gem. This gem contains--among other things--a command-line tool for easily encrypting GitHub tokens.
+
+Run the following command to install the Travis gem:
 
-. Install travis gem:
-+
   $ gem install travis
-+
-. Enable Travis CI for your Jekyll repository:
-.. open your https://travis-ci.org/profile/[profile page] on Travis,
-.. find the repository and turn on the switch,
-.. then click on repository settings (next to the switch) and enable “Build only if .travis.yml is present.”
-. Generate a new personal access token on GitHub:
-.. open https://github.com/settings/tokens/new[this page] to generate a new personal access token,
-.. select the scope _public_repo_, fill some description and confirm.
-. Encrypt the token and add it to your `.travis.yml`:
-.. replace `<token>` with the GitHub token and execute:
-+
+
+=== Enable Travis CI
+
+Travis CI is configured initially through a browser.
+
+To activate Travis CI for the Repository:
+
+. Open https://travis-ci.org and create an account.
+. Open your https://travis-ci.org/profile/[profile page] on Travis.
+. Find the Jekyll repositorysitory, and turn on the switch.
+. Click on repositorysitory settings (next to the switch) and enable “Build only if .travis.yml is present.”
+
+=== Generate a GitHub Personal Access Token
+
+Once the repository is activated in Travis, you need a GitHub token to pass into the Travis keytool.
+
+To generate a new personal access token on GitHub:
+
+. Open https://github.com/settings/tokens/new.
+. Select the scope _public_repository_, and add a terse description.
+. Confirm and save the settings.
+
+=== Encrypt the GitHub Token for Travis CI
+
+With the GitHub token created, you can now pass it to the Travis command-line tool, which adds the encryped value to a file in your repository.
+
+To encrypt the token and add it to the `.travis.yml` file:
+
+. Move into the same directory as `env.global`.
+. Run the following command, replacing `<token>` with the GitHub token from the previous step.
+
   $ travis encrypt GH_TOKEN=<token> --add env.global
-+
-.. and check that it added something like the following to `.travis.yml`:
+
+. Verify the script added the `secure` global environment variable to `.travis.yml`:
 +
 [source, yaml]
 ----
 env:
   global:
-    secure: YOUR-ENCRYPTED-TOKEN
+    secure: [YOUR-ENCRYPTED-TOKEN]
 ----
-. Commit changes, push to GitHub and check that Travis has started the job and finished it successfully.
++
+. Commit all changes, and push to GitHub.
+
+=== Verify the Configuration
+
+To verify if you have configured the repository correctly, open https://travis-ci.org and verify that Travis starts, and subsequenty finishes processing the job.
+
+Travis places the built site into the _gh-pages_ branch upon completion.
+
+== Summary
+
+If you can load the `[username].github.io/index.html/` home page, you have successfully completed basic configuration.
+
+Start writing blog posts and enjoy the AsciiDoc difference, regardless of what device you choose: computer, tablet, or mobile.