James W.D. Stewart

James W.D. Stewart

Embrace "The Suck"


Home  •  About  •  Blog  •  Blogroll  •  Contact  •  Donate  •  Freelance  •  Gallery  •  In Case of Emergency  •  Résumé  •  Socialize  •  The Suck

 

 

 

Share to:  E-mail  •  Facebook  •  Google+  •  LinkedIn  •  Pinterest  •  Reddit  •  Tumblr  •  Twitter

 

What is static site generation?

/blog/2017/04/02/static-site-generation/

https://forces.army/blog/2017/04/02/static-site-generation/

Static Site Generation

Count Words — Reading Time
by James Stewart
Published: 
Updated:    Spelling
Location:  200 Larch St., Sudbury, Ontario, P3E 1C5, Canada
 

 

What is static site generation?

  • Use a program to produce HTML pages.
    • Analogous to compiling computer programs.
    • Source Code  →  Machine Code
  • Development Cycle
    • Write the Source
    • Compile
    • Inspect and/or Test the Result
  • Examples
    • Jekyll
      • Transform your plain text into static Web sites and blogs.
      • Used by GitHub Pages.
    • Middleman
      • Build static Web sites with an easy-to-use framework.  Middleman is a static site generator using all the shortcuts and tools in modern Web development.
    • More…

 

Middleman:  A Ruby Gem

  • Project is a directory (i.e. "myproj")
        $ middleman init myproj
        
    • Configuration files, README, Gemfile, etc.
  • Create source files in "myproj/source".
    • Sub-directries for CSS. images, etc.
  • Compile all of the source files.
        $ bundle exec middleman build
        
  • Result is placed in "myproj/build".
  • Copy the site to some visible location.
        $ rsync -avz --del myproj/build ~/WWW
        
  • Or, preview locally (i.e. live reload, no build).
        $ bundle exec middleman server
        

 

Why bother?

  1. Code reuse and single-point-of-control over change.
  2. Authoring of content in a language that's more human-friendly.
  3. Parameterized generation of markup and content.

Let's look at each of these benefits in turn…

 

Motivation #1:  Visual Identity

  • Common headers & footers.
  • Duplication of code is EVIL.
    • Corollary:  Cut-and-paste is EVIL.
    • Destroys single-point-of-control over change.
  • Solution:
    • Put common HTML in one file (a "partial").
    • Every document includes that file.

 

ERb:  Embedded Ruby

  • General templating mechanism.
    • A string (usually contents of a file, "template").
      • Escaped bits of ruby.
        • Execute ruby code (i.e. "scriplet").
                          <% code %>
                          
        • Replace with result of expr.
                          <%= expr %>
                          
        • Ignore (i.e. a comment).
                          <%# text %>
                          
  • Example:  A text file.
        This is some text.
        <% 5.times do %>
        Current Time is <%= Time.now %>!
        <% end %>
        
  • Process using erbtool to generate result.
        $ erb example.txt.erb > example.txt
        
  • Naming Convention:  filename.outputlang.erb
    • Example:  index.html.erb
  • Many alternatives (i.e. HAML).

 

Generation of Site

  • Source files in "myproj/source".
        $ ls source
        index.html.erb    syll.html.erb
        meet.html.erb
        
  • Compile.
        $ bundle exec middleman build
        
  • Result after building.
        $ ls build
        index.html    meet.html    syll.html
        

 

Partials

  • A document fragment included in other documents.
  • Include in ERb using the partial function.
        <body>
          <%= partial "navigation" %>
          ...
        </body>
        
  • Partial's filename begins with "_".
    • i.e. _navigation.erb
              <div class="navbar">
                <ul id="site-nav">
                  <li>...</li>
                </ul>
              </div>
              
      • Note:  "_" omitted in argument to function.

 

Generation of Site with Partials

  • Source files in myproj/source.
        $ ls source
        _footer.erb        meet.html.erb
        _navigation.erb    syll.html.erb
        index.html.erb 
        
  • Compile.
        $ bundle exec middleman build
        
  • Result after building.
        $ ls build
        index.html    meet.html    syll.html
        

 

Tricks with Partials

  • Content of partial can be customized by passing arguments in call.
  • In Calling ERb:  Pass a hash.
        <%= partial "banner", :locals => { :name => "Syllabus", :amount => 34 } %>
        
  • In Partial:  Access variables.
        <h3><%= :name %></h3>
        <p>Costs <%= "$#{:amount}.00" %></p>
        

 

Problem

  • How to guarantee every page includes partial(s).
    • Partials don't ensure one page structure across the site.
  • Every page should look like:
        <!DOCTYPE html>
        <html>
          <head>
            <meta charset="utf-8">
            <title>Meetings</title>
            <link href="osu_style.css" rel="stylesheet" type="text/css" />
          </head>
          <body>
            <%= partial "navigation" %>
            ...  <!--different on each page-->
          </body>
        </html>
        

 

Solution:  Layout

  • HTML formed from:  Layout + Template
  • Layout is the overall structure of the HTML page.
  • File:  layout.erb
        <!DOCTYPE html>
        <html>
          <head>
            <meta charset="utf-8">
            <title>  ...  etc
          </head>
          <body>
            <%= yield =>
          </body>
        
  • Template replaces layout's yield.
  • Layout is where you put site-wide styling.
    • i.e. navigation bar, div's with CSS classes, footers

 

Page-Specific Data in Layout

  • Some layout content is page-specific.
    • Example:  <title> in document's head.
  • Solution:  Ruby variable current_page
    • Example:  current_page.path
  • Template contains "frontmatter" that sets the value of current_page.data.
    • In template (contact.html.erb)
              ;;;
              "title": "Contact Information"
              ;;;
              
    • In layout (layout.erb)
              <title><%= current_page.data.title %></title>
              

 

Generation of Site with Layouts

  • Default layout in "source/layouts/layouts.erb".
        $ ls –F source
        index.html.erb    meet.html.erb
        layouts/          syll.html.erb
        
        $ ls source/layouts
        _footer.erb    _navigation.erb    layout.erb
        
  • Result after building.
        $ ls build
        index.html    meet.html    syll.html
        

 

Motive #2:  Improved Syntax

  • HTML tags make content hard to read.
    • <p>, <h2>, <em>, <a href='…'> etc
    • Versus plain text, which is easier to read.
  • Common plain text conventions:
    • Blank lines between paragraphs.
    • Underline titles with –'s or ='s.
    • Emphasize ∗words∗, _words_, ∗∗words∗∗.
    • Links in ( )'s.
    • Unordered lists with bullets using * or -.
    • Numbered lists with 1., 2., 3.

 

Markdown

  • Formalizes these ASCII conventions.
    • Filename Extension:  .md
    • Adds some less familiar ones (i.e. ```).
  • Tools generate corresponding HTML.
    • Examples:  GitHub readme's, user-posted comments on Web boards (i.e. StackOverflow).
  • Other target languages possible too.
  • See Markdown's README.md
  • Warning:  Many Markdown dialects.

 

CSS Limitations

  • Literals are common.
        h1 {
          background-color: #ff14a6;
        }
    
        h2 {
          color: #ff14a6;
        }
        
  • Result:  Lack of single-point-of-control.
  • Solution:  SASS, allows variables.
        $primary: #ff14a6;
    
        h1 {
          background-color: $primary;
        }
    
        h2 {
          color: $primary;
        }
        
  • Preprocessor generates CSS from SASS.

 

Motive #3:  Content Generation

  • Iterate over an array to create content.
    • Example:  Rows of a table.
    • See course Web site.
    • Partial could be used for (every) row.
  • Placeholder text and images.
        <%= lorem.sentence %>
        
    • Many versions of this "helper" are available.
              lorem.paragraphs 2
              lorem.date
              lorem.last_name
              lorem.image('300x400')
      
                #=>  http://placehold.it/300x400
              

 

More Helper Functions

  • Links.
        <%= link_to 'About', '/about.html' %>
    
          #=>  <a href='/about/'>About</a>
        
  • Assets.
        <%= stylesheet_link_tag 'all' %>
        <%= javascript_include_tag 'jquery' %>
        <%= favicon_tag 'images/favicon.png' %>
        <%= link_to 'Blog', '/blog', :class => 'example' %>
        <%= image_tag 'padrino.png', :width => '35', :class => 'logo' %>
        

 

Summary

  • ERb
    • Template for generating HTML.
    • Scriplets and expressions.
  • Reuse of views with partials.
    • Included with partial (eg <%= partial…).
    • Filename is prepended with underscore.
    • Parameter passing from parent template.
  • Layouts and templates.
  • Markdown, SASS.
  • Content generation and helpers.

 
Categories:  Technology  
Tags:  How to

 
Syndicated to:

 
References:

  1. Jekyll
    by Innominate Referenced: 
  2. Middleman
    by Thomas Reynolds Referenced: 
  3. Static Site Generators
    by Innominate Referenced: 

 

Share to:  E-mail  •  Facebook  •  Google+  •  LinkedIn  •  Pinterest  •  Reddit  •  Tumblr  •  Twitter

 

 

 

 


DISCLAIMER:  Neither the forces.army domain nor any of its sub-domains are associated with and/or sponsored by any national and/or international government agency or branch of the armed forces in any nation.


Atom  •  Comments  •  Privacy Policy  •  Sitemap  •  Terms and Conditions

 
IndieWebCamp
 
 
Links Monetized by VigLink
 

Creative Commons Licence :: BY-NC-SA James W.D. Stewart by James Stewart is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.  Based on a work at https://github.com/jwds1978/jwds1978.github.io.