Juliette Reinders Folmer - Promote your open source project with GitHub Pages - Codemotion Milan 2017
0 likes362 views
The document outlines the importance and benefits of using GitHub Pages for promoting open source projects, emphasizing discoverability, usability, and credibility. It details the setup process, static site generation with Jekyll, and essential features like customizing URL structures and integrating with the GitHub API. Various resources and examples are provided to help users effectively utilize GitHub Pages for their projects.
![@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']](https://image.slidesharecdn.com/zvbwawssoabxyiff9cda-signature-3918075a2b94c7c637e64428b02f4c0bf95f626a67b6ec7e17416e64360a079a-poli-171120142833/85/Juliette-Reinders-Folmer-Promote-your-open-source-project-with-GitHub-Pages-Codemotion-Milan-2017-27-320.jpg)
{: 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>](https://image.slidesharecdn.com/zvbwawssoabxyiff9cda-signature-3918075a2b94c7c637e64428b02f4c0bf95f626a67b6ec7e17416e64360a079a-poli-171120142833/85/Juliette-Reinders-Folmer-Promote-your-open-source-project-with-GitHub-Pages-Codemotion-Milan-2017-47-320.jpg)
Juliette Reinders Folmer - Promote your open source project with GitHub Pages - Codemotion Milan 2017
- 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
- 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 GHWiki 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 ? -- ++ + +/- ++
- 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 ? RougeKramdown LiquidJekyll
- 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
- 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
- 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 %}
- 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/
- 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