Pro Yearly is on sale from $80 to $50! »

Show off your Open Source Project with GitHub Pages

Show off your Open Source Project with GitHub Pages

Presented on May 31th 2016 at the International PHP Conference, Berlin, Germany.
https://phpconference.com/
---------------------------------------------------------------
Are you hosting the code of an open source project on GitHub? Or do you quickly want to get a simple site online without having to arrange for hosting, configuring a server etc? GitHub Pages might be the solution for you. GitHub Pages allows you to build a site based on markdown text files. Add in some Jekyll, Liquid and kramdown magic and you can pull in the changelog of your project from GitHub, show off a list of the contributors to the project, have download links which automagically point to the latest release of your GH hosted project and more. Learn what GH Pages are and how to get them online and who knows by the end of the session, you might decide this is the right solution for *you*.

Transcript

  1. Juliette Reinders Folmer | Advies en zo Show off your

    Open Source Project with GitHub Pages
  2. @jrf_nl #ghpages Who Am I? Self-employed, Independent Consultant Training Author

    at Pluralsight pluralsight.com Contributor to many open source projects
  3. @jrf_nl #ghpages Does my open source project need a website

    ? (Hint: YES!)
  4. @jrf_nl #ghpages Why ? discoverability usability credibility

  5. @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
  6. @jrf_nl #ghpages Introducing GitHub Pages

  7. @jrf_nl #ghpages Static Site Generator

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

    static site
  9. @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
  10. @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 ? -- ++ + +/- ++
  11. @jrf_nl #ghpages Free Fast Open

  12. @jrf_nl #ghpages Open Collaboration Website

  13. @jrf_nl #ghpages

  14. @jrf_nl #ghpages GitHub Pages in Practice

  15. @jrf_nl #ghpages Types Type Site Branch User <username>.github.io master Organisation

    <orgname>.github.io master Project <username>.github.io/<projectname> <orgname>.github.io/<projectname> gh-pages
  16. @jrf_nl #ghpages How It Works • Orphan branch • Site

    regenerated on push to gh-pages branch master gh-pages
  17. @jrf_nl #ghpages What Do You Get ? Rouge Kramdown Liquid

    Jekyll
  18. @jrf_nl #ghpages Plugins jekyll- redirect- fom jekyll- sitemap jekyll-seo- tag

    jekyll- mentions jekyll-gist jekyll-feed jemoji jekyll-sass- converter
  19. @jrf_nl #ghpages Basic Set Up

  20. @jrf_nl #ghpages Gem File source 'https://rubygems.org' gem 'github-pages' Branch: gh-pages/master

    Location: / Filename: Gemfile https://pages.github.com/versions/
  21. @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']
  22. @jrf_nl #ghpages Git Ignore _site/* Gemfile.lock Branch: gh-pages/master Location: /

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

    / Filename: CNAME
  24. @jrf_nl #ghpages DNS Settings www or custom subdomain CNAME <user>.github.io

    APEX domain ALIAS, ANAME or A 192.30.252.153 192.30.252.154
  25. @jrf_nl #ghpages Working With

  26. @jrf_nl #ghpages Directory Layout / _drafts _includes _layouts _posts _sass

    assets css js images
  27. @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']
  28. @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 ---
  29. @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
  30. @jrf_nl #ghpages Working With Liquid

  31. @jrf_nl #ghpages Liquid Basics # Output {{ variable | filter

    }} # Tags {% tag %}
  32. @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 }}
  33. @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
  34. @jrf_nl #ghpages Creating Output <h3>Recent posts</h3> <ul> {% for post

    in site.posts | limit: 5 %} <li> <a href="{{ post.url | remove: 'index.html' | prepend: site.github.url }}">{{ post.title }}</a><br /> <span class="post-meta"><a href="{{ post.author | url_escape | prepend: 'https://github.com/' }}"> @{{ post.author }}</a> | <time datetime="{{ post.date | date: '%F %R' }}"> {{ post.date | date_to_string }}</time></span> </li> {% endfor %} </ul>
  35. @jrf_nl #ghpages

  36. @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 %}
  37. @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 %}
  38. @jrf_nl #ghpages Rouge Code Highlighting {% highlight php %} <?php

    foreach ( $attendees as $attendee ) { echo 'IPC and Webinale rock!'; } {% endhighlight %}
  39. @jrf_nl #ghpages Rouge Code Highlighting {% highlight php %} <?php

    foreach ( $attendees as $attendee ) { echo 'IPC and Webinale rock!'; } {% endhighlight %} https://github.com/mojombo/tpw/blob/master/css/syntax.css https://github.com/richleland/pygments-css/blob/master/github.css
  40. @jrf_nl #ghpages Working With the GitHub API

  41. @jrf_nl #ghpages Useful Variables From the API {{ site.github.url }}

    # http://<user>.github.io/<project> {{ site.github.repository_url }} # https://github.com/<user>/<project> {{ site.github.zip_url }} {{ site.github.tar_url }} {{ site.github.clone_url }}
  42. @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 }}
  43. @jrf_nl #ghpages Adding Release Table <div class="releases"> {%if site.github.releases %}

    <table> <tr><th>Release</th><th>Version</th><th>Released on</th><th colspan="2">Download</th></tr> {% for release in site.github.releases limit:3 %} <tr> <td><a href="{{ release.html_url }}">{{ release.name }}</a></td> <td>{{ release.published_at | date_to_string }}</td> <td><a href="{{ release.zipball_url }}">Zip</a></td> <td><a href="{{ release.tarball_url }}">Tar</a></td> </tr> {% endfor %} </table> {% endif %}
  44. @jrf_nl #ghpages

  45. @jrf_nl #ghpages Adding Changelogs {% if site.github.releases %} ##### Changelog

    {% for release in site.github.releases limit:1 %} <div class="changelog">{{ release.body | markdownify }}</div> {% endfor %} {% endif %}
  46. @jrf_nl #ghpages

  47. @jrf_nl #ghpages Showing Off Contributors <div class="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 %} </div>
  48. @jrf_nl #ghpages

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

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

  51. @jrf_nl #ghpages Testing Your Build

  52. @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
  53. @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
  54. @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/
  55. Questions ?

  56. @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)
  57. Thank you ! Slides will be posted to http://speakerdeck.com/jrf Please

    rate this talk on https://joind.in/talk/761f4