Learning Modules

This page identifies divides the workshop into a series of learning modules.

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

Build a Website with a Static Website Generator

Module #1: Project Basics

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?

Module #2: Preparing your Linux / Mac / Windows workstation

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

Module #3: 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

Module #4: 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 #5: Add content to a static page

• 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

Module #6: 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)

Module #7: Add non-text content

• Where do I put images?

• How do I add images to my page?

• How do I add metadata?

Module #8: Customize look & feel / theme

• How do I modify the layouts?

• How do I modify the styles?

  Sidebar: SASS & Foundation primer

Module #9: 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?

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