From 127704ad1775eade80bc4a920de73ed0e0970e13 Mon Sep 17 00:00:00 2001 From: alexmalik Date: Sat, 1 Oct 2016 23:14:12 +0100 Subject: [PATCH 1/6] Replace backticks with HTML tags Prior to the change backticks were used in an attempt to create a code block. The problem is that inside block level HTML tags Markdown is not supported. I have replaced the backticks with a combination of HTML tags in order to approximately simulate the appearance of a code block. The docs suggest possible use of span tags in place of the surrounding div tags as a solution to getting the Markdown to render. I tried this but no success. This change improves the readers understanding of the information, because the reader doesn't have to make sense of raw markdown. --- docs/_docs/github-pages.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/_docs/github-pages.md b/docs/_docs/github-pages.md index b65bad904..f07af766b 100644 --- a/docs/_docs/github-pages.md +++ b/docs/_docs/github-pages.md @@ -54,26 +54,22 @@ few minor details. currently-deployed version of the gem in your project, add the following to your Gemfile: -```ruby -source 'https://rubygems.org' +

source 'https://rubygems.org'

-require 'json' -require 'open-uri' -versions = JSON.parse(open('https://pages.github.com/versions.json').read) +

require 'json'

+

require 'open-uri'

+

versions = JSON.parse(open('https://pages.github.com/versions.json').read)

-gem 'github-pages', versions['github-pages'] -``` +

gem 'github-pages', versions['github-pages']

This will ensure that when you run bundle install, you have the correct version of the github-pages gem. If that fails, simplify it: -```ruby -source 'https://rubygems.org' +

source 'https://rubygems.org'

-gem 'github-pages' -``` +

gem 'github-pages'

And be sure to run bundle update often. From c47ae465ad6e27f5f335f96f5834da8c2959cfc9 Mon Sep 17 00:00:00 2001 From: alexmalik Date: Sun, 2 Oct 2016 13:31:15 +0100 Subject: [PATCH 2/6] Replace p and code tags with {% highlight %} --- docs/_docs/github-pages.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/_docs/github-pages.md b/docs/_docs/github-pages.md index f07af766b..449e45152 100644 --- a/docs/_docs/github-pages.md +++ b/docs/_docs/github-pages.md @@ -53,24 +53,33 @@ few minor details. differences between various versions of the gems. To use the currently-deployed version of the gem in your project, add the following to your Gemfile: +

-

source 'https://rubygems.org'

+ {% highlight ruby %} + source 'https://rubygems.org' -

require 'json'

-

require 'open-uri'

-

versions = JSON.parse(open('https://pages.github.com/versions.json').read)

+ require 'json' + require 'open-uri' + versions = JSON.parse(open('https://pages.github.com/versions.json').read) -

gem 'github-pages', versions['github-pages']

+ gem 'github-pages', versions['github-pages'] + {% endhighlight %} +

This will ensure that when you run bundle install, you have the correct version of the github-pages gem. If that fails, simplify it: +

-

source 'https://rubygems.org'

-

gem 'github-pages'

+ {% highlight ruby %} + source 'https://rubygems.org' + gem 'github-pages' + {% endhighlight %} + +

And be sure to run bundle update often. If you like to install pages-gem on Windows you can find instructions by Jens Willmer on how to install github-pages gem on Windows (x64). From a41b46ff35e375ba5847abe5af1671c35aa21fa8 Mon Sep 17 00:00:00 2001 From: alexmalik Date: Tue, 4 Oct 2016 12:11:52 +0100 Subject: [PATCH 3/6] replace {% %} with bacticks for nested code-block uses Kramdown with the markdown="1" attribute, as suggested by @mmistakes. This allows rendering of code blocks which are nested inside HTML tags. --- docs/_docs/github-pages.md | 62 ++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 32 deletions(-) diff --git a/docs/_docs/github-pages.md b/docs/_docs/github-pages.md index 449e45152..b82baa186 100644 --- a/docs/_docs/github-pages.md +++ b/docs/_docs/github-pages.md @@ -42,48 +42,46 @@ There are two basic types available: user/organization pages and project pages. The way to deploy these two types of sites are nearly identical, except for a few minor details. -

-
Use the github-pages gem
-

- Our friends at GitHub have provided the - github-pages - gem which is used to manage Jekyll and its dependencies on - GitHub Pages. Using it in your projects means that when you deploy - your site to GitHub Pages, you will not be caught by unexpected - differences between various versions of the gems. To use the - currently-deployed version of the gem in your project, add the - following to your Gemfile: -

+
+##### Use the `github-pages` gem - {% highlight ruby %} - source 'https://rubygems.org' +Our friends at GitHub have provided the +github-pages +gem which is used to manage Jekyll and its dependencies on +GitHub Pages. Using it in your projects means that when you deploy +your site to GitHub Pages, you will not be caught by unexpected +differences between various versions of the gems. To use the +currently-deployed version of the gem in your project, add the +following to your `Gemfile`: - require 'json' - require 'open-uri' - versions = JSON.parse(open('https://pages.github.com/versions.json').read) +
+```ruby +source 'https://rubygems.org' - gem 'github-pages', versions['github-pages'] - {% endhighlight %} +require 'json' +require 'open-uri' +versions = JSON.parse(open('https://pages.github.com/versions.json').read) -

- This will ensure that when you run bundle install, you - have the correct version of the github-pages gem. +gem 'github-pages', versions['github-pages'] +``` +

- If that fails, simplify it: -

+This will ensure that when you run `bundle install`, you +have the correct version of the `github-pages` gem. +If that fails, simplify it: - {% highlight ruby %} - source 'https://rubygems.org' +
+```ruby +source 'https://rubygems.org' - gem 'github-pages' - {% endhighlight %} +gem 'github-pages' +``` +
-

- And be sure to run bundle update often. +And be sure to run `bundle update` often. - If you like to install pages-gem on Windows you can find instructions by Jens Willmer on how to install github-pages gem on Windows (x64). -

+If you like to install `pages-gem` on Windows you can find instructions by Jens Willmer on how to install github-pages gem on Windows (x64).
From 2009749e58bad922e697eb0f5d4206f0b84c2bf7 Mon Sep 17 00:00:00 2001 From: alexmalik Date: Tue, 4 Oct 2016 12:19:30 +0100 Subject: [PATCH 4/6] add new style rule for .code-block class as suggested by @ashmaroli --- docs/_sass/_style.scss | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/_sass/_style.scss b/docs/_sass/_style.scss index 5e4419245..f1e3de5f3 100644 --- a/docs/_sass/_style.scss +++ b/docs/_sass/_style.scss @@ -670,6 +670,11 @@ h5 > code, font-size: 0.8em; } +.code-block { + margin: 10px 0; + code { background: none; } +} + .highlight { margin: 1em 0; padding: 10px 0; From 9cd71aaea9e8f780e2789cbc3a5d02ad92927e27 Mon Sep 17 00:00:00 2001 From: alexmalik Date: Tue, 4 Oct 2016 14:34:24 +0100 Subject: [PATCH 5/6] add empty div with markdown="1" attribute an empty div is necessary in order for the code blocks to render correctly when not displayed on the jekyllrb site. --- docs/_docs/github-pages.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/_docs/github-pages.md b/docs/_docs/github-pages.md index b82baa186..a93b65b5b 100644 --- a/docs/_docs/github-pages.md +++ b/docs/_docs/github-pages.md @@ -43,6 +43,9 @@ The way to deploy these two types of sites are nearly identical, except for a few minor details.
+
+
+ ##### Use the `github-pages` gem Our friends at GitHub have provided the @@ -55,6 +58,9 @@ currently-deployed version of the gem in your project, add the following to your `Gemfile`:
+
+
+ ```ruby source 'https://rubygems.org' @@ -72,6 +78,9 @@ have the correct version of the `github-pages` gem. If that fails, simplify it:
+
+
+ ```ruby source 'https://rubygems.org' From df80f6fd2a70cde7eaa305dda4d157dcfab1c251 Mon Sep 17 00:00:00 2001 From: alexmalik Date: Tue, 25 Oct 2016 12:10:31 +0100 Subject: [PATCH 6/6] Replace html links with markdown links --- docs/_docs/github-pages.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/_docs/github-pages.md b/docs/_docs/github-pages.md index a93b65b5b..b046f0f91 100644 --- a/docs/_docs/github-pages.md +++ b/docs/_docs/github-pages.md @@ -27,7 +27,7 @@ site builds properly, use `site.github.url` in your URL's. -{{ page.title }} +[{{ page.title }}]("{{ page.url | prepend: site.github.url }}") {% endraw %} ``` @@ -49,7 +49,7 @@ few minor details. ##### Use the `github-pages` gem Our friends at GitHub have provided the -github-pages +[github-pages](https://github.com/github/pages-gem) gem which is used to manage Jekyll and its dependencies on GitHub Pages. Using it in your projects means that when you deploy your site to GitHub Pages, you will not be caught by unexpected @@ -90,7 +90,8 @@ gem 'github-pages' And be sure to run `bundle update` often. -If you like to install `pages-gem` on Windows you can find instructions by Jens Willmer on how to install github-pages gem on Windows (x64). +If you like to install `pages-gem` on Windows you can find instructions by Jens Willmer on +[how to install github-pages gem on Windows (x64)]("http://jwillmer.de/blog/tutorial/how-to-install-jekyll-and-pages-gem-on-windows-10-x46#github-pages-and-plugins").
@@ -107,8 +108,7 @@ If you like to install `pages-gem` on Windows you can find instructions by Jens User and organization pages live in a special GitHub repository dedicated to only the GitHub Pages files. This repository must be named after the account -name. For example, [@mojombo’s user page -repository](https://github.com/mojombo/mojombo.github.io) has the name +name. For example, [@mojombo’s user page repository](https://github.com/mojombo/mojombo.github.io) has the name `mojombo.github.io`. Content from the `master` branch of your repository will be used to build and @@ -156,9 +156,8 @@ to see more detailed examples.
GitHub Pages Documentation, Help, and Support

For more information about what you can do with GitHub Pages, as well as for - troubleshooting guides, you should check out GitHub’s Pages Help - section. If all else fails, you should contact GitHub Support. + troubleshooting guides, you should check out + GitHub’s Pages Help section. + If all else fails, you should contact GitHub Support.