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 %} [{: 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