Dano Manion

Jekyll Notes

Github Pages

What is a Project Site?

  • This is the most common type of site you’ll see on github pages, Usually:
    • A Project Landing Page
    • Marketing Site
    • Front-end web Technolgy demo
  • Deployed to username.github.io/reponame
  • Can setup custom domains
  • Based on Jekyll
  • Can be generated through the GUI

What is Jekyll?

  • Jekyll is a static site generator. Think of it like a content management system (CMS), without all the complexity and headache. No need to build a giant content-strangling Rube Goldberg machine to “manage” content, if all you’re doing at the end of the day is putting out HTML, Javascript, and CSS, the building blocks of the internet. As a result, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content. source

  • Jekyll is a static site engine
  • Features:
    • repo metadata
    • sitemaps
    • atom feeds link to docs
    • redirects
    • custom 404 pages
    • sass
    • redirect plugin that can redirect both to local and non-local pages
      • Example: file: docs.md

          ---
          redirect_to: https://example.com/docs/
          ---
        
    • Emoji
  • Link to default setting

How do I deactivate Jekyll rendering for Github pages? For example: If I just want to render regular HTML Markup.

  • Add this to your repo /.nojekyll

What are the defaults when using Github Pages?

  • Syntax highlighter - pigments
  • Enforces Safe setting to true, forbids 3rd party plugins
  • Enforces LSI setting to false (Produce an index for related posts)
  • Resets source setting to repo root directory

What is Github pages Meta data?

  • Meta data is the data Github has setup on their servers for access to your site if you so choose
  • you can add YOUR release info (if you wanted to) and pages built with github pages can expose that. Would make sense if you were building some sort of platform or page with a team and had scheduled releases.

  • Repo Metadata on Github

Front Matter

What is front matter?

  • Front matter is a powerfull jekyll feature that lets you set variables on a page.

      Example page
    
      ---
      # The lines tell Jekyll we are using front-matter
    	
      # set variable 
      hello_text: "Hello there!" 
    	
      # Boolean
      show_footer: true
    	
      # Arrays 
      fruit:
          - apple
          - pear
          - durian
          - star fruit
          - banana
    
      # Objects
      vegetables
          - name: pepper
            cost: $1.29
            color: green
          - name: tomato
            cost: $0.89
            color: red
          - name: lettuce
            cost: $0.69
            color: green
      ---
    	
      <h1>{{ page.hello_text }}</h1>
    	
      <h2>Fruits</h2>
      <ul>
          {% for item in page.fruit %}
              <li>{{ item }}</li>
          {% endfor %}
      </ul>
    	
      <h2>Vegetables</h2>
      <ul>
          {% for item in page.fruit %}
              <li>{{ item.name }}, costs: {{ item.cost }}, color: {{ item.color }}</li>
          {% endfor %}
      </ul>
    	
      {{ if page.show_footer }}
      <footer>I am a footer.</footer>
      {{ endif }}
    

What is Liquid?

  • Liquid is a simple templating language jekyll uses to process pages on your site.
    • Loops
    • Add Content
    • Have conditionals
  • Examples of Liquid

What are Collections?

  • Collections are groups of data that aren’t really pages or posts, they are sort of like definitions of objects.
  • Link with lot’s more info

      +-------------------------------------+         +----------------+
      | Can the things be logically grouped?|---No--->|    Use pages   |
      +-------------------------------------+         +----------------+
                      |
                     Yes
                      |
                      V
      +-------------------------------------+         +----------------+
      |      Are they grouped by date?      |---No--->|Use a collection|
      +-------------------------------------+         +----------------+
                      |
                     Yes
                      |
                      V
      +-------------------------------------+
      |            Use posts                |
      +-------------------------------------+
    

What are posts?

  • Posts are pages that can be grouped together, Examples like Blog come to mind.
  • One benefit to posts is that you can do stuff like site.tags and site.categories in the YAML
    • this is great for surfacing “related” content
    • pages cannot do this

Data Files

  • Data files can be YAML, JSON, or CSV, are placed in /_data/, and are accessible with site.data.

Jekyll Commands

  • How do I run it on my source directory?

      jekyll serve
    	
      # Only update newer posts
      jekyll serve --incremental regeneration 
    
  • Build a site and output it to a source directory?

      jekyll build
    	
      # Show stats and buildtimes 
      jekyll build --profile
    
  • Build the website and include draft posts

      jekyll build --drafts
    
  • Build and change the source ….

      jekyll build -s <PATH>
    
  • Build and change the destination

      jekyll build -d <PATH>
    
  • Trigger safe mode so you know how it works without plugins

      jekyll build --safe 
    
  • Build and watch the directory for changes and rebuild. serve actually does this already.

      jekyll build -w
    
  • Pass an enviroment variable

      JEKYLL_ENV=development jekyll build
    
  • Publish blog posts with a date in the future

      jekyll build --future
    
  • Generating related posts

      jekyll build --lsi
    
  • Generate only a few posts

      jekyll build --limit_posts 20
    
  • Force updates if changes are rebuildign

      jekyll build --force_polling
    
  • Verbose

      jekyll build --verbose
    
  • Quiet

      jekyll build --queit
    

– Only build the new stuff

	jekyll build --incremental

Plugins

Supported by GitHub Pages

SEO

  • Change permalinks
  • Default: permalink: /:title/ - Change to permalink: date or permalink: pretty to get fancy URLs with dates in them.

Misc

Github has hooks that auto compile your site code.

PrinceXML will convert HTML to PDF with CSS Stlying

Sources

  1. https://mademistakes.com/articles/using-jekyll-2016/
  2. WebJeda’s - 9 Must do Jekyll SEO optimizations