Learning Modules

Overarching goal: Create a website hosted on GitHub Pages to use for reporting your experiences at OSCON

Module #1: Prepare your workstation

Setup Ruby

• How do I install Ruby on Linux / Mac / Windows?

Setup publishing toolchain

• How do I install git?

• How do I install required gems?

  • awestruct

  • asciidoctor

  • bundler

  Sidebar: What is a gem?

Setup execution PATH

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

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

Module #2: Setup and publish website

Initiate / create a 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

Publish the site

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

Module #3: Add content to website

Add static page

• 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 create a new page?

  • choose folder/filename

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

  • set layout

• 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

Setup a blog

• How do I activate the blog in Awestruct?

  Sidebar: Awestruct pipeline

• How do I setup layouts for the blog index & posts

  Note	Make boilerplate code available on wiki

  Sidebar: layout files and Haml (or Slim)

• How do I make a new blog post?

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

(git serves as your blog admin backend)

Add non-text content

• Where do I put images?

• How do I add images to my page?

• How do I add metadata?

Module #4: Customize look & feel / theme

• How do I modify the layouts?

• How do I modify the styles?

  Sidebar: SASS & Foundation primer

Module #5: Automatic publishing

• 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?

Module #6: Collaborating

• How does collaboration work?

• How do I propose a revision or new content?

  Sidebar: Pull request primer

• How do I send revisions to someone else’s proposal?

Other possible modules / lessons

• "Edit this file" button

• RSS feed

• Google Analytics

• Disqus comments

• Selecting a text editor

• Site navigation

• +1 button