Promote your open source project with GitHub Pages

Presented on November 10th 2017 at Codemotion Milan - 5th anniversary edition, Milan, Italy.
https://milan2017.codemotionworld.com/
---------------------------------------------------------------
Need a website for an open source project of which the code is on GitHub ? GitHub Pages might be a viable option. GitHub Pages allows you to build a site based on simple markdown text files and with a sprinkling of magic stardust you can pull in the changelog of your project from GitHub, show off a list of the contributors to the project and more. Join me to learn what GH Pages are and how to get your project web presence with little effort.

Transcript

1. @jrf_nl #ghpages Promote your Open Source Project with GitHub Pages Juliette Reinders Folmer CODEMOTION MILAN - SPECIAL EDITION 10 – 11 NOVEMBER 2017
2. @jrf_nl #ghpages Does my open source project need a website ? (Hint: YES!)
3. @jrf_nl #ghpages Why ? discoverability usability credibility
4. @jrf_nl #ghpages Content ? • What is it ? • Why should I use it ? • Features • Roadmap • Development Blog • Download link • How to install • How to use • Documentation
5. @jrf_nl #ghpages Introducing GitHub Pages
6. @jrf_nl #ghpages Static Site Generator
7. @jrf_nl #ghpages Static site Pre- generated static site Jekyll generated static site
8. @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
9. @jrf_nl #ghpages WordPress or other CMS GH Wiki GH Pages static GH Pages pre- generated GH Pages with Jekyll Findability + -/+ + + + Usability + - + + + Ease of 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 ? -- ++ + +/- ++
10. @jrf_nl #ghpages Free Fast Open
11. @jrf_nl #ghpages Open Collaboration Website
12. @jrf_nl #ghpages GitHub Pages in Practice
13. @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 • /docs subdir of master
14. @jrf_nl #ghpages How It Works • Orphan branch • Site regenerated on push to gh-pages branch or master /docs subdirectory master gh-pages
15. @jrf_nl #ghpages
16. @jrf_nl #ghpages
17. @jrf_nl #ghpages
18. @jrf_nl #ghpages What Do You Get ? Rouge Kramdown Liquid Jekyll
19. @jrf_nl #ghpages Plugins jekyll-redirect- from jekyll-sitemap jekyll-seo-tag jekyll- mentions jekyll-gist jekyll-feed jemoji jekyll-sass- converter
20. @jrf_nl #ghpages Basic Set Up
21. @jrf_nl #ghpages Gem File source 'https://rubygems.org' gem 'github-pages' Branch: gh-pages/master Location: / Filename: Gemfile https://pages.github.com/versions/
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 plugins: - 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 • none • ordinal • 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 'Codemotion Milan 2017 rocks!'; } {% endhighlight %}
39. @jrf_nl #ghpages Rouge Code Highlighting {% highlight php %} <?php foreach ( $attendees as $attendee ) { echo 'Codemotion Milan 2017 rocks!'; } {% 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 a Releases 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 Change- logs {% 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 e5af95370fdb834ad7d696b4112c8d0c %}
50. @jrf_nl #ghpages Showing Your Gists {% gist 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. @jrf_nl #ghpages 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. @jrf_nl #ghpages Thank you ! Slides will be posted to http://speakerdeck.com/jrf