Show off your Open Source Project with GitHub Pages

Slide 1

Slide 1 text

Juliette Reinders Folmer | Advies en zo Show off your Open Source Project with GitHub Pages

Slide 2

Slide 2 text

@jrf_nl #ghpages Who Am I? Self-employed, Independent Consultant Training Author at Pluralsight pluralsight.com Contributor to many open source projects

Slide 3

Slide 3 text

@jrf_nl #ghpages Does my open source project need a website ? (Hint: YES!)

Slide 4

Slide 4 text

@jrf_nl #ghpages Why ? discoverability usability credibility

Slide 5

Slide 5 text

@jrf_nl #ghpages What ? • What is it ? • Why should I use it ? • Features • Roadmap • Development Blog • Download link • How to install • How to use • Documentation

Slide 6

Slide 6 text

@jrf_nl #ghpages Introducing GitHub Pages

Slide 7

Slide 7 text

@jrf_nl #ghpages Static Site Generator

Slide 8

Slide 8 text

@jrf_nl #ghpages Static site Pre- generated static site Jekyll generated static site

Slide 9

Slide 9 text

@jrf_nl #ghpages Pre-generated vs Jekyll Make changes Push to src branch Locally build site Push to GH Pages branch Make changes Push to GH Pages branch

Slide 10

Slide 10 text

@jrf_nl #ghpages WordPress or other platform GH Wiki GH Pages static GH Pages pre- generated GH Pages with Jekyll Findability + -/+ + + + Usability + - + + + Ease off contributing same login ? -- + + + + testing locally ? - -- ++ - +/- reviewability ? + - ++ (PR) ++ (PR) ++ (PR) auditability ? - +/- (history) ++ ++ ++ access to GH API ? +/- via plugin or custom code -- -- via custom js code + via custom code + at push extendability ? ++ -- - ++ - threshold to contribute ? -- ++ + +/- ++

Slide 11

Slide 11 text

@jrf_nl #ghpages Free Fast Open

Slide 12

Slide 12 text

@jrf_nl #ghpages Open Collaboration Website

Slide 13

Slide 13 text

@jrf_nl #ghpages

Slide 14

Slide 14 text

@jrf_nl #ghpages GitHub Pages in Practice

Slide 15

Slide 15 text

@jrf_nl #ghpages Types Type Site Branch User .github.io master Organisation .github.io master Project .github.io/ .github.io/ gh-pages

Slide 16

Slide 16 text

@jrf_nl #ghpages How It Works • Orphan branch • Site regenerated on push to gh-pages branch master gh-pages

Slide 17

Slide 17 text

@jrf_nl #ghpages What Do You Get ? Rouge Kramdown Liquid Jekyll

Slide 18

Slide 18 text

@jrf_nl #ghpages Plugins jekyll- redirect- fom jekyll- sitemap jekyll-seo- tag jekyll- mentions jekyll-gist jekyll-feed jemoji jekyll-sass- converter

Slide 19

Slide 19 text

@jrf_nl #ghpages Basic Set Up

Slide 20

Slide 20 text

@jrf_nl #ghpages Gem File source 'https://rubygems.org' gem 'github-pages' Branch: gh-pages/master Location: / Filename: Gemfile https://pages.github.com/versions/

Slide 21

Slide 21 text

@jrf_nl #ghpages More Comprehensive Gem File source 'https://rubygems.org' require 'json' require 'open-uri' versions = JSON.parse(open('https://pages. github.com/versions.json').read) gem 'github-pages', versions['github-pages']

Slide 22

Slide 22 text

@jrf_nl #ghpages Git Ignore _site/* Gemfile.lock Branch: gh-pages/master Location: / Filename: .gitignore

Slide 23

Slide 23 text

@jrf_nl #ghpages Using Your Own Domain yourdomainname.com Branch: gh-pages/master Location: / Filename: CNAME

Slide 24

Slide 24 text

@jrf_nl #ghpages DNS Settings www or custom subdomain CNAME .github.io APEX domain ALIAS, ANAME or A 192.30.252.153 192.30.252.154

Slide 25

Slide 25 text

@jrf_nl #ghpages Working With

Slide 26

Slide 26 text

@jrf_nl #ghpages Directory Layout / _drafts _includes _layouts _posts _sass assets css js images

Slide 27

Slide 27 text

@jrf_nl #ghpages .config.yml baseurl: / highlighter: rouge markdown: kramdown permalink: /:year/:month/:day/:title/ encoding: UTF-8 kramdown: input: GFM auto_id_prefix: "h-" parse_block_html: true gems: - jekyll-mentions exclude: ['CNAME', '.gitignore', '.travis.yml', 'Gemfile', 'CONTRIBUTING.md', 'LICENSE', 'README.md']

Slide 28

Slide 28 text

@jrf_nl #ghpages Front Matter --- title: How do I get started with Jekyll ? permalink: /installing-jekyll/ layout: default published: false date: YYYY-MM-DD HH:MM:SS +/-TTTT (posts only) category: install tags: - tag1 - tag2 ---

Slide 29

Slide 29 text

@jrf_nl #ghpages URL Structure 1. _config.yml permalink: date # = {:categories/:year/ :month/:day/:title.html} # other options: • pretty • ordinal • none • custom 2. frontmatter --- permalink: /custom-url/ --- 3. via directory structure

Slide 30

Slide 30 text

@jrf_nl #ghpages Working With Liquid

Slide 31

Slide 31 text

@jrf_nl #ghpages Liquid Basics # Output {{ variable | filter }} # Tags {% tag %}

Slide 32

Slide 32 text

@jrf_nl #ghpages Jekyll Variables # Sitewide info + info from _config.yml {{ site }} # Page/post info + page front matter {{ page }} ### {{page.title}} # All posts (files) in /_posts/ {{ site.posts }} # All pages {{ site.pages }} # The content of the page or post being generated {{ content }}

Slide 33

Slide 33 text

@jrf_nl #ghpages {{ variable | filters | more filters }} append / prepend: 'string' capitalize downcase / upcase escape(_once) xml_escape strip_html strip_newlines newline_to_br replace: 'foo','bar' markdownify slugify date_to_xmlschema date_to_rfc822 date_to_string date_to_long_string ceil floor sort size map

Slide 34

Slide 34 text

@jrf_nl #ghpages Creating Output

Slide 35

Slide 35 text

@jrf_nl #ghpages

Slide 36

Slide 36 text

@jrf_nl #ghpages Tags {% for var in varhash %} # do something {% endfor %} {% case condition %} {% when 'public' %} # do something else {% when 'private' %} # do something else {% endcase %} {% if var.size > 5 %} # do something {% else %} # do something else {% endif %} # Including partials {% include footer.html %}

Slide 37

Slide 37 text

@jrf_nl #ghpages Other Useful Tricks {% capture generate_date %} {{ site.time | date: "%Y%m%d" }} {% endcapture %} {{ 'style.css?v=' | append generate_date }} {% assign sorted_categories = ( site.categories | sort:0 %} {% raw %} Some content with conflicting {{{tags}}}. {% endraw %} {% comment %} This will be ignored when the site is build. {% endcomment %}

Slide 38

Slide 38 text

@jrf_nl #ghpages Rouge Code Highlighting {% highlight php %}

Slide 39

Slide 39 text

@jrf_nl #ghpages Rouge Code Highlighting {% highlight php %}

Slide 40

Slide 40 text

@jrf_nl #ghpages Working With the GitHub API

Slide 41

Slide 41 text

@jrf_nl #ghpages Useful Variables From the API {{ site.github.url }} # http://.github.io/ {{ site.github.repository_url }} # https://github.com// {{ site.github.zip_url }} {{ site.github.tar_url }} {{ site.github.clone_url }}

Slide 42

Slide 42 text

@jrf_nl #ghpages Useful Variables From the API {{ site.github.project_title }} # Repository name {{ site.github.project_tagline }} # Repository description {{ site.github.owner_name }} # nick {{ site.github.owner_url }}

Slide 43

Slide 43 text

@jrf_nl #ghpages Adding Release Table

{%if site.github.releases %} {% for release in site.github.releases limit:3 %} {% endfor %} ReleaseVersionReleased onDownload {{ release.name }} {{ release.published_at | date_to_string }} Zip Tar {% endif %}

Slide 44

Slide 44 text

@jrf_nl #ghpages

Slide 45

Slide 45 text

@jrf_nl #ghpages Adding Changelogs {% if site.github.releases %} ##### Changelog {% for release in site.github.releases limit:1 %}

{% endfor %} {% endif %}

Slide 46

Slide 46 text

@jrf_nl #ghpages

Slide 47

Slide 47 text

@jrf_nl #ghpages Showing Off Contributors

{% for contributor in site.github.contributors %} [![Avatar]({{ contributor.avatar_url }}){: style="width: 30px;"}]({{ contributor.html_url }}) [@{{ contributor.login }}]({{ contributor.html_url }}) {: .contributor } {% else %} This project would not be possible without the help of [our amazing contributors]( {{ '/graphs/contributors' | prepend: site.github.url }} ) on GitHub. {% endfor %}

Slide 48

Slide 48 text

@jrf_nl #ghpages

Slide 49

Slide 49 text

@jrf_nl #ghpages Showing Your Gists {% gist jrfnl/e5af95370fdb834ad7d696b4112c8d0c %}

Slide 50

Slide 50 text

@jrf_nl #ghpages Showing Your Gists {% gist jrfnl/e5af95370fdb834ad7d696b4112c8d0c %}

Slide 51

Slide 51 text

@jrf_nl #ghpages Testing Your Build

Slide 52

Slide 52 text

@jrf_nl #ghpages Testing Your Build branches: only: - gh-pages language: ruby cache: bundler rvm: - 2.1.0 script: # Test the build - bundle exec jekyll build

Slide 53

Slide 53 text

@jrf_nl #ghpages Setting Up a Local Environment • https://www.ruby-lang.org/en/downloads/ Install Ruby • > gem install bundler Install Bundler Make sure you have created a Gemfile • projectdir> bundle install Install gems

Slide 54

Slide 54 text

@jrf_nl #ghpages Testing Locally # Always make sure your gems are up to date projectdir> bundle update # Build it and watch for changes projectdir> bundle exec jekyll serve View in browser: http://localhost:4000/

Slide 55

Slide 55 text

Questions ?

Slide 56

Slide 56 text

@jrf_nl #ghpages Useful Links • https://pages.github.com/ • https://help.github.com/categories/ customizing-github-pages/ • https://jekyllrb.com/ • https://github.com/Shopify/liquid/wiki/ Liquid-for-Designers • https://help.github.com/articles/ repository-metadata-on-github-pages/ • http://ghpages.info/ (coming soon)

Slide 57

Slide 57 text

Thank you ! Slides will be posted to http://speakerdeck.com/jrf Please rate this talk on https://joind.in/talk/761f4

Slide 1

Slide 1 text

Slide 2

Slide 2 text

Slide 3

Slide 3 text

Slide 4

Slide 4 text

Slide 5

Slide 5 text

Slide 6

Slide 6 text

Slide 7

Slide 7 text

Slide 8

Slide 8 text

Slide 9

Slide 9 text

Slide 10

Slide 10 text

Slide 11

Slide 11 text

Slide 12

Slide 12 text

Slide 13

Slide 13 text

Slide 14

Slide 14 text

Slide 15

Slide 15 text

Slide 16

Slide 16 text

Slide 17

Slide 17 text

Slide 18

Slide 18 text

Slide 19

Slide 19 text

Slide 20

Slide 20 text

Slide 21

Slide 21 text

Slide 22

Slide 22 text

Slide 23

Slide 23 text

Slide 24

Slide 24 text

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Slide 27

Slide 27 text

Slide 28

Slide 28 text

Slide 29

Slide 29 text

Slide 30

Slide 30 text

Slide 31

Slide 31 text

Slide 32

Slide 32 text

Slide 33

Slide 33 text

Slide 34

Slide 34 text

Recent posts

Slide 35

Slide 35 text

Slide 36

Slide 36 text

Slide 37

Slide 37 text

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Slide 40