improved installation instructions

matuzalemmuller · Oct 8, 2016 · b69693e · b69693e
1 parent bbd495a
commit b69693e
Show file tree

Hide file tree

Showing 18 changed files with 119 additions and 72 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/Gemfile b/Gemfile
@@ -1,5 +1,3 @@
 source "https://rubygems.org"
 
-# gem "rails"
-gem 'github-pages'
-gem 'jekyll'
+gem 'github-pages', group: :jekyll_plugins
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -13,34 +13,35 @@ GEM
       execjs
     coffee-script-source (1.10.0)
     colorator (1.1.0)
-    ethon (0.9.0)
+    ethon (0.9.1)
       ffi (>= 1.3.0)
     execjs (2.7.0)
     faraday (0.9.2)
       multipart-post (>= 1.2, < 3)
     ffi (1.9.14)
     forwardable-extended (2.6.0)
     gemoji (2.1.0)
-    github-pages (94)
+    github-pages (98)
       activesupport (= 4.2.7)
       github-pages-health-check (= 1.2.0)
       jekyll (= 3.2.1)
       jekyll-coffeescript (= 1.0.1)
       jekyll-feed (= 0.5.1)
       jekyll-gist (= 1.4.0)
-      jekyll-github-metadata (= 2.0.2)
+      jekyll-github-metadata (= 2.1.1)
       jekyll-mentions (= 1.2.0)
       jekyll-paginate (= 1.1.0)
       jekyll-redirect-from (= 0.11.0)
       jekyll-sass-converter (= 1.3.0)
       jekyll-seo-tag (= 2.0.0)
       jekyll-sitemap (= 0.10.0)
+      jekyll-swiss (= 0.4.0)
       jemoji (= 0.7.0)
       kramdown (= 1.11.1)
       liquid (= 3.0.6)
       listen (= 3.0.6)
       mercenary (~> 0.3)
-      minima (= 1.0.1)
+      minima (= 1.2.0)
       rouge (= 1.11.1)
       terminal-table (~> 1.4)
     github-pages-health-check (1.2.0)
@@ -68,7 +69,7 @@ GEM
     jekyll-feed (0.5.1)
     jekyll-gist (1.4.0)
       octokit (~> 4.2)
-    jekyll-github-metadata (2.0.2)
+    jekyll-github-metadata (2.1.1)
       jekyll (~> 3.1)
       octokit (~> 4.0)
     jekyll-mentions (1.2.0)
@@ -83,6 +84,7 @@ GEM
     jekyll-seo-tag (2.0.0)
       jekyll (~> 3.1)
     jekyll-sitemap (0.10.0)
+    jekyll-swiss (0.4.0)
     jekyll-watch (1.5.0)
       listen (~> 3.0, < 3.1)
     jemoji (0.7.0)
@@ -98,18 +100,16 @@ GEM
       rb-inotify (>= 0.9.7)
     mercenary (0.3.6)
     mini_portile2 (2.1.0)
-    minima (1.0.1)
-    minitest (5.9.0)
+    minima (1.2.0)
+    minitest (5.9.1)
     multipart-post (2.0.0)
     net-dns (0.8.0)
-    nokogiri (1.6.8)
+    nokogiri (1.6.8.1)
       mini_portile2 (~> 2.1.0)
-      pkg-config (~> 1.1.7)
     octokit (4.3.0)
       sawyer (~> 0.7.0, >= 0.5.3)
     pathutil (0.14.0)
       forwardable-extended (~> 2.6)
-    pkg-config (1.1.7)
     public_suffix (1.5.3)
     rb-fsevent (0.9.7)
     rb-inotify (0.9.7)
@@ -120,21 +120,20 @@ GEM
     sawyer (0.7.0)
       addressable (>= 2.3.5, < 2.5)
       faraday (~> 0.8, < 0.10)
-    terminal-table (1.7.0)
-      unicode-display_width (~> 1.1)
+    terminal-table (1.7.3)
+      unicode-display_width (~> 1.1.1)
     thread_safe (0.3.5)
     typhoeus (0.8.0)
       ethon (>= 0.8.0)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    unicode-display_width (1.1.0)
+    unicode-display_width (1.1.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   github-pages
-  jekyll
 
 BUNDLED WITH
-   1.12.5
+   1.13.2
diff --git a/_config.yml b/_config.yml
@@ -55,7 +55,7 @@ kramdown:
 
 collections:
   tooltips:
-    output: false
+    output: true
 # collections are declared here. this renders the content in _tooltips and processes it, but doesn't output it as actual files in the output unless you change output to true
 
 defaults:

diff --git a/_data/.DS_Store b/_data/.DS_Store
diff --git a/_includes/custom/getting_started_series_next.html b/_includes/custom/getting_started_series_next.html
@@ -1,4 +1,3 @@
-
 <p>{% assign series_pages = site.tags.series_acme %}
     {% for p in pages %}
     {% if p.series == "Getting Started" %}

diff --git a/_includes/custom/series_acme_next.html b/_includes/custom/series_acme_next.html
@@ -1,10 +1,30 @@
-<p>{% assign series_pages = site.tags.series_acme %}
-    {% for p in pages %}
-    {% if p.series == "ACME series" %}
-    {% assign nextTopic = page.weight | plus: "1"  %}
-    {% if p.weight == nextTopic  %}
-    <a href="{{p.url | remove: "/"}}"><button type="button" class="btn btn-primary">Next: {{p.weight}}  {{p.title}}</button></a>
-    {% endif %}
-    {% endif %}
-    {% endfor %}
-</p>
+<div class="seriesContext">
+    <a>
+        {% assign pages = site.pages | sort:"weight"  %}
+        {% for pg in pages %}
+        {% if pg.series == "ACME series" %}
+        {% if pg.weight > page.weight %}
+        <a href="{{pg.url | remove: '/'}}"><button type="button" class="btn btn-primary">Next: {{pg.title}}</button></a>
+        {% break %}
+        {% endif %}
+        {% endif %}
+        {% endfor %}
+    </a>
+    &nbsp;
+    <div class="btn-group">
+        <button type="button" data-toggle="dropdown" class="btn btn-primary dropdown-toggle">Jump to: <span class="caret"></span></button>
+        <ol class="dropdown-menu">
+            {% for pg in pages %}
+            {% if pg.series == "ACME series" %}
+            {% if pg.url == page.url %}
+            <li class="active"> → {{pg.weight}}. {{pg.title}}</li>
+            {% else %}
+            <li>
+                <a href="{{pg.url | remove: '/'}}">{{pg.title}}</a>
+            </li>
+            {% endif %}
+            {% endif %}
+            {% endfor %}
+        </ol>
+    </div>
+</div>
diff --git a/css/.DS_Store b/css/.DS_Store
diff --git a/css/customstyles.css b/css/customstyles.css
@@ -896,6 +896,28 @@ span.soft {
     max-height: 100%;
 }
 
+
+.post-content img {
+    margin: 12px 0px 3px 0px;
+    width: auto;
+    height: auto;
+    max-width: 100%;
+    max-height: 100%;
+}
+.col-md-9 img {
+    max-width: 100%;
+    max-height: 100%;
+}
+
+
+.post-content img {
+    margin: 12px 0px 3px 0px;
+    width: auto;
+    height: auto;
+    max-width: 100%;
+    max-height: 100%;
+}
+
 .videoThumbs img {
     float: left;
     margin:15px 15px 15px 0px;

diff --git a/index.md b/index.md
@@ -7,52 +7,66 @@ permalink: index.html
 summary: These brief instructions will help you get started quickly with the theme. The other topics in this help provide additional information and detail about working with other aspects of this theme and Jekyll.
 ---
 
-## Download or clone the theme
+## Download the theme
 
-First download or clone the theme from the [Github repo](https://github.com/tomjohnson1492/documentation-theme-jekyll). Most likely you won't be pulling in updates once you start customizing the theme, so downloading the theme (instead of cloning it) probably makes the most sense.
+First download or clone the theme from the [Github repo](https://github.com/tomjohnson1492/documentation-theme-jekyll). Most likely you won't be pulling in updates once you start customizing the theme, so downloading the theme (instead of cloning it) probably makes the most sense. In Github, click the **Clone or download** button, and then click **Download ZIP**.
 
-## Build this theme
+## Install Jekyll
 
-If you're used to running Jekyll sites, you can type the normal jekyll command, `jekyll serve`, to build the Jekyll theme. However, if you're a new Jekyll user or if you run into issues, see the following two topics:
+If you've never installed or run a Jekyll site locally on your computer, follow these instructions to install Jekyll:
 
 * [Install Jekyll on Mac][mydoc_install_jekyll_on_mac]
 * [Install Jekyll on Windows][mydoc_install_jekyll_on_windows]
 
-## Customize the Gemfile
+## Install Bundler
 
-The Gemfile is how project dependencies are managed. This project doesn't have any dependencies beyond core Jekyll. 
-
-Open the Gemfile (in any text editor) in the Jekyll doc theme project with the following command:
+In case you haven't installed Bundler, install it:
 
 ```
-open Gemfile
+gem install bundler
 ```
 
-The theme's gemfile looks as follows:
+You'll want [Bundler](http://bundler.io/) to make sure all the Ruby gems needed work well with your project. Bundler sorts out dependencies and installs missing gems or matches up gems with the right versions based on gem dependencies.
+
+## Remove the Gemfiles
+
+The Gemfile is how project dependencies are managed. Although this project includes a Gemfile, this theme doesn't have any dependencies beyond core Jekyll. The Gemfile is used to specify gems needed for publishing on Github Pages. If you're not planning to have Github Pages build your Jekyll project, delete these two files from the theme's root directory:
 
+* Gemfile
+* Gemfile.lock
+
+## Build the Project (not with the Github Pages gem)
+
+If you've never run Jekyll on your computer (you can check with `jekyll --version`), you may need to install the jekyll gem:
+
+```
+gem install jekyll
 ```
-# A sample Gemfile
-source "https://rubygems.org"
 
-# gem "rails"
-gem 'github-pages'
-gem 'jekyll'
+Now run Jekyll serve (first change directories (`cd`) to where you downloaded the project):
+
+```
+jekyll serve
 ```
 
-If you're publishing on Github Pages, leave the `github-pages` gem there. But if not, remove `github-pages` because Github sometimes has dependencies that conflict with the latest versions of the Jekyll gem and Kramdown, which can be frustrating.
+## Build the Project (with the Github Pages gem)
 
-Use Bundler to install all the needed Ruby gems:
+If you *are* in fact publishing on Github Pages, leave the Gemfile and Gemfile.lock files in the theme, along with the Github Pages gem specified in the Gemfile (`gem 'github-pages', group: :jekyll_plugins`). However, note that you cannot use the normal `jekyll serve` command with this gem due to dependency conflicts between the latest version of Jekyll and Github Pages (which are noted [briefly here](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/). 
+
+You need Bundler to resolve these dependency conflicts. Use Bundler to install all the needed Ruby gems:
 
 ```
-bundle install
+bundle update
 ```
 
-Now run Jekyll serve to build the theme:
+Then *always* use this command to build Jekyll:
 
 ```
-jekyll serve
+bundle exec jekyll serve
 ```
 
+(If you want to shorten this long command, you can put this code in a file such as jekyll.sh (on a Mac) and then simply type `. jekyll.sh` to build Jekyll.)
+
 ## Configure the sidebar
 
 There are several products in this theme. Each product uses a different sidebar. This is the essence of what makes this theme unique -- different sidebars for different product documentation. The idea is that when users are reading documentation for a specific product, the sidebar navigation should be specific to that product. (You can read more of my thoughts on why multiple sidebars are important in this [blog post](http://idratherbewriting.com/2016/03/23/release-of-documentation-theme-for-jekyll-50/).)

diff --git a/js/.DS_Store b/js/.DS_Store
diff --git a/pages/.DS_Store b/pages/.DS_Store
diff --git a/pages/mydoc/mydoc_series.md b/pages/mydoc/mydoc_series.md
@@ -11,7 +11,7 @@ folder: mydoc
 
 ## Using series for pages
 
-You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a [demo][mydoc_seriesdemo1]</a>.
+You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a <a href="mydoc_seriesdemo1.html">demo</a>.
 
 ## 1. Create the series button
 

diff --git a/pages/mydoc/mydoc_seriesdemo1.md b/pages/mydoc/mydoc_seriesdemo1.md
@@ -9,14 +9,14 @@ permalink: mydoc_seriesdemo1.html
 folder: mydoc
 ---
 
-{% include custom/series_acme.html %}
+{% include custom/series_acme_next.html %}
 
 This is the first post in the series.
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
 
-{% include custom/series_acme_next.html %}
+
 
 {% include links.html %}
diff --git a/pages/mydoc/mydoc_seriesdemo2.md b/pages/mydoc/mydoc_seriesdemo2.md
@@ -10,7 +10,7 @@ folder: mydoc
 ---
 
 
-{% include custom/series_acme.html %}
+{% include custom/series_acme_next.html %}
 
 This is the second post in the series.
 
@@ -20,6 +20,5 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo.
 
-{% include custom/series_acme_next.html %}
 
 {% include links.html %}
diff --git a/pages/mydoc/mydoc_seriesdemo3.md b/pages/mydoc/mydoc_seriesdemo3.md
@@ -10,7 +10,7 @@ permalink: mydoc_seriesdemo3.html
 folder: mydoc
 ---
 
-{% include custom/series_acme.html %}
+{% include custom/series_acme_next.html %}
 
 This is the third post in the series.
 
@@ -20,6 +20,5 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
 
-{% include custom/series_acme_next.html %}
 
 {% include links.html %}
diff --git a/pages/mydoc/mydoc_seriesdemo4.md b/pages/mydoc/mydoc_seriesdemo4.md
@@ -10,7 +10,7 @@ folder: mydoc
 ---
 
 
-{% include custom/series_acme.html %}
+{% include custom/series_acme_next.html %}
 
 This is the fourth post in the series.
 
@@ -23,7 +23,4 @@ Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fer
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius.
 
-
-{% include custom/series_acme_next.html %}
-
 {% include links.html %}