Learning Modules - graphitefriction/oscon-2013-docs-workshop GitHub Wiki

A quick overview of the tools we’ll use to create the website.

1. Project Introduction (2-3m)

2. Introduction to the console and text editor

3. Introduction to Ruby (3m)

4. Introduction to git (3m)

5. Introduction to gems and bundler (3m)

6. Introduction to awestruct

7. Introduction to asciidoctor

   Sidebar: What is a gem?

What about jekyll and github pages?

Using a console and text editor, we’ll learn how to install and setup the tools needed to create and launch the website.

1. Setting up Ruby

   1. Console Hands On: Install Ruby

2. Getting and installing the required gems

   1. Console Hands On: Install awestruct, asciidoctor, and bundler

3. Setting up git

   1. Console Hands On: Install git

4. Setup execution PATH

   • How do I get awestruct, asciidoctor, bundle (from bundler) and git on my PATH?

     Should be able to type: <application> --version

5. Choosing your text editor

With the built-in CSS grid system and styles, we’ll launch a default Awestruct website.

• How do I create a new site?

  • Create a new directory for the site

  • Switch to directory

  • Run Awestruct: awestruct -i -f foundation

  Sidebar: What are Bootstrap and Foundation? Which should you choose?

• What are the post-create steps?

  • bundle install

  Sidebar: What is bundler (and the bundle command)?

• How do I preview my site?

  • rake

  • View http://localhost:4242 in browser

• How do I create a new page?

  • choose folder/filename

  • AsciiDoc content structure (title, author, paragraph content)

  • set layout

• How do I write the content? What format do I use?

  Sidebar: What is AsciiDoc, why use it? What is content strategy and/or chunked content?

• How do I link to my new page?

• How do I preview my new page? (A: as above)

• How do I publish my new changes? (git add, git commit, git push, awestruct deploy)

• How do I view my page outside of Awestruct?

  • Locally

  • On GitHub

Sidebar: Overview of GitHub Pages

• How do I create a GitHub account?

• How do I setup git to use the GitHub account?

(Refer to bootcamp on help.github.com for the previous two lessons)

• How do I create a repository on GitHub to host the site (e.g., oscon-report)

• How do I convert my site a local Git repository?

• How do I get my site into the repository on GitHub?

  • git remote add

  • git push main branch (master?)

  • Configure Awestruct github-pages deployer

  • Run Awestruct deployer: awestruct deploy

  • Wait a bit

  • Access <username>.github.io/oscon-report in your browser

1. Project Introduction

2. Awestruct pipeline

   Sidebar: Awestruct pipeline * How do I setup layouts for the blog index & posts

   + NOTE: Make boilerplate code available on wiki

3. Haml and Slim Introduction Sidebar: layout files and Haml (or Slim)

4. Sass and Foundation Introduction

   Sidebar: SASS & Foundation primer

5. Travis CI introduction

• How do I activate the blog in Awestruct?

Are there default settings or best practices for organizing? Upgrading? Backing up?

You’ll learn how to add, tag, and categorize blog posts.

• Creating a new blog post

• Writing the blog post’s header and metadata with AsciiDoc syntax

• Adding media to your blog post

• How do I publish my blog post? (A: as above)

• How does the automatic publishing work?

  • Jekyll - automatic

  • Awestruct - via Travis CI

• How do I setup a Travis account?

• How do I link my Travis account to my GitHub account?

• How do I activate Travis on my repository?

• How do I configure Travis to publish my site? (git serves as your blog admin backend)

Configure? Gravatars?

• How do I modify the layouts?

• How do I modify the styles?

1. Typography, images, video, audio, include files and data, social

2. Responsive grid and elements

3. Plugins, JQuery, JavaScript

• Where do I put images?

• How do I add images to my page?

• How do I add metadata?