diff --git a/_config.yml b/_config.yml index cc34ebd..7adb61a 100644 --- a/_config.yml +++ b/_config.yml @@ -18,7 +18,7 @@ disqus_shortname: idrbwjekyll # if you're using disqus for comments, add the shortname here. if not, leave this value blank. host: 127.0.0.1 # the preview server used. Leave as is. -port: 4009 +port: 4005 # the port where the preview is rendered. You can leave this as is unless you have other Jekyll builds using this same port that might cause conflicts. exclude: diff --git a/_data/urls.yml b/_data/urls.yml index 3a00ce8..89fcbff 100644 --- a/_data/urls.yml +++ b/_data/urls.yml @@ -1,22 +1,5 @@ - - - - - - - - - -mydoc_homepage: - title: "Get started" - url: "/documentation-theme-jekyll/" - link: "Get started" - - - - mydoc_release_notes_50: title: "5.0 Release notes" url: "/documentation-theme-jekyll/mydoc_release_notes_50/" @@ -585,6 +568,3 @@ p2_landing_page: url: "p2_landing_page" link: "Product 2" - - - diff --git a/_includes/sidebar.html b/_includes/sidebar.html index f233444..4020086 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -12,7 +12,7 @@ {% for item in subcategory.items %} {% if item.output contains "web" %} {% if item.external_url %} -
  • {{subcategory.title}}
    • +
  • {{item.title}}
    • {% elsif page.url == item.url %}
  • {{item.title}}
    • {% else %} diff --git a/css/customstyles.css b/css/customstyles.css index e8e2c9e..7eba3c3 100644 --- a/css/customstyles.css +++ b/css/customstyles.css @@ -72,16 +72,16 @@ body { .breadcrumb > .active {color: #777 !important;} /* make room for the nav bar */ -/*h1[id],*/ -/*h2[id],*/ -/*h3[id],*/ -/*h4[id],*/ -/*h5[id],*/ -/*h6[id],*/ -/*dt[id]{*/ -/*padding-top: 60px; */ -/*margin-top: -40px*/ -/*}*/ +h1[id], +h2[id], +h3[id], +h4[id], +h5[id], +h6[id], +dt[id]{ +padding-top: 60px; +margin-top: -40px +} body h1 {margin-top:40px;} diff --git a/mydoc/mydoc_about_ruby_gems_bundler.md b/mydoc/mydoc_about_ruby_gems_bundler.md index 2bd2fa3..0c586f3 100644 --- a/mydoc/mydoc_about_ruby_gems_bundler.md +++ b/mydoc/mydoc_about_ruby_gems_bundler.md @@ -13,7 +13,7 @@ Jekyll runs on Ruby, a programming language. You have to have Ruby on your compu ## About Ruby Gems -Ruby has a number of plugins referred to as "gems." Just because you have Ruby doesn't mean you have all the necessary Ruby gems that your program needs to run. Gems provide additional functionality for Ruby programs. There are literally *millions* of [Rubygems](https://rubygems.org/) available for you to use. +Ruby has a number of plugins referred to as "gems." Just because you have Ruby doesn't mean you have all the necessary Ruby gems that your program needs to run. Gems provide additional functionality for Ruby programs. There are thousands of [Rubygems](https://rubygems.org/) available for you to use. Some gems depend on other gems for functionality. For example, the Jekyll gem might depend on 20 other gems that must also be installed. @@ -21,7 +21,7 @@ Each gem has a version associated with it, and not all gem versions are compatib ## Rubygem package managers -[Bundler](http://bundler.io/) is a gem package manager for Ruby, which means it goes out and gets all the gems you need for your Ruby programs. If you tell Bundler you need the Jekyll gem, it will retrieve all the dependencies on the Jekyll gem as well -- automatically. +[Bundler](http://bundler.io/) is a gem package manager for Ruby, which means it goes out and gets all the gems you need for your Ruby programs. If you tell Bundler you need the [jekyll gem](https://rubygems.org/gems/jekyll), it will retrieve all the dependencies on the jekyll gem as well -- automatically. Not only does Bundler retrieve the right gem dependencies, but it's smart enough to retrieve the right versions of each gem. For example, if you get the [github-pages](https://rubygems.org/gems/github-pages) gem, it will retrieve all of these other gems: @@ -49,14 +49,9 @@ RedCloth = 4.2.9 rouge = 1.10.1 terminal-table ~> 1. ``` - -Note that Bundler goes out and retrieves not only the gem, but the right version of the gem. - -You'll see here that the github-pages gem requires version 3.0.3 of the jekyll gem. - -However, the latest version of the jekyll gem is 3.1.2. This means that github-pages is compatible with only an older version of the jekyll gem. +See how Bundler retrieved version 3.0.3 of the jekyll gem, even though (as of this writing) the latest version of the jekyll gem is 3.1.2? That's because github-pages is only compatible up to jekyll 3.0.3. Bundler handles all of this dependency and version compatibility for you. -Trying to keep track of which gems and versions are appropriate for your project can be a nightmare. This is the problem Bundler solves. They [explain](http://bundler.io/): + Trying to keep track of which gems and versions are appropriate for your project can be a nightmare. This is the problem Bundler solves. As explained on [Bundler.io](http://bundler.io/): > Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed. > @@ -73,7 +68,7 @@ gem 'github-pages' gem 'jekyll' ``` -The source indicates the site where Bundler will retrieve the gems: https://rubygems.org. +The source indicates the site where Bundler will retrieve the gems: [https://rubygems.org](https://rubygems.org). The gems it retrieves are listed separately on each line. @@ -90,7 +85,7 @@ To specify a subset of versions, the Gemfile looks like this: ``` gem 'jekyll', '~> 2.3' ``` -The `~>` sign means greater than or equal to the last digit before the last period in the number. +The `~>` sign means greater than or equal to the *last digit before the last period in the number*. Here it will get any gem equal to 2.3 but less than 3.0. @@ -112,3 +107,145 @@ This will get any Jekyll gem between versions 3.0 and up to 3.0.3. See this [Stack Overflow post](http://stackoverflow.com/questions/5170547/what-does-tilde-greater-than-mean-in-ruby-gem-dependencies) for more details. +## Gemfile.lock + +After Bundler retrieves and installs the gems, it makes a detailed list of all the gems and versions it has installed for your project. The snapshot of all gems + versions installed is stored in your Gemfile.lock file, which might look like this: + +``` +GEM + remote: https://rubygems.org/ + specs: + RedCloth (4.2.9) + activesupport (4.2.5.1) + i18n (~> 0.7) + json (~> 1.7, >= 1.7.7) + minitest (~> 5.1) + thread_safe (~> 0.3, >= 0.3.4) + tzinfo (~> 1.1) + addressable (2.3.8) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.10.0) + colorator (0.1) + ethon (0.8.1) + ffi (>= 1.3.0) + execjs (2.6.0) + faraday (0.9.2) + multipart-post (>= 1.2, < 3) + ffi (1.9.10) + gemoji (2.1.0) + github-pages (52) + RedCloth (= 4.2.9) + github-pages-health-check (= 1.0.1) + jekyll (= 3.0.3) + jekyll-coffeescript (= 1.0.1) + jekyll-feed (= 0.4.0) + jekyll-gist (= 1.4.0) + jekyll-mentions (= 1.0.1) + jekyll-paginate (= 1.1.0) + jekyll-redirect-from (= 0.9.1) + jekyll-sass-converter (= 1.3.0) + jekyll-seo-tag (= 1.3.1) + jekyll-sitemap (= 0.10.0) + jekyll-textile-converter (= 0.1.0) + jemoji (= 0.5.1) + kramdown (= 1.9.0) + liquid (= 3.0.6) + mercenary (~> 0.3) + rdiscount (= 2.1.8) + redcarpet (= 3.3.3) + rouge (= 1.10.1) + terminal-table (~> 1.4) + github-pages-health-check (1.0.1) + addressable (~> 2.3) + net-dns (~> 0.8) + octokit (~> 4.0) + public_suffix (~> 1.4) + typhoeus (~> 0.7) + html-pipeline (2.3.0) + activesupport (>= 2, < 5) + nokogiri (>= 1.4) + i18n (0.7.0) + jekyll (3.0.3) + colorator (~> 0.1) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 1.1) + kramdown (~> 1.3) + liquid (~> 3.0) + mercenary (~> 0.3.3) + rouge (~> 1.7) + safe_yaml (~> 1.0) + jekyll-coffeescript (1.0.1) + coffee-script (~> 2.2) + jekyll-feed (0.4.0) + jekyll-gist (1.4.0) + octokit (~> 4.2) + jekyll-mentions (1.0.1) + html-pipeline (~> 2.3) + jekyll (~> 3.0) + jekyll-paginate (1.1.0) + jekyll-redirect-from (0.9.1) + jekyll (>= 2.0) + jekyll-sass-converter (1.3.0) + sass (~> 3.2) + jekyll-seo-tag (1.3.1) + jekyll (~> 3.0) + jekyll-sitemap (0.10.0) + jekyll-textile-converter (0.1.0) + RedCloth (~> 4.0) + jekyll-watch (1.3.1) + listen (~> 3.0) + jemoji (0.5.1) + gemoji (~> 2.0) + html-pipeline (~> 2.2) + jekyll (>= 2.0) + json (1.8.3) + kramdown (1.9.0) + liquid (3.0.6) + listen (3.0.6) + rb-fsevent (>= 0.9.3) + rb-inotify (>= 0.9.7) + mercenary (0.3.5) + mini_portile2 (2.0.0) + minitest (5.8.4) + multipart-post (2.0.0) + net-dns (0.8.0) + nokogiri (1.6.7.2) + mini_portile2 (~> 2.0.0.rc2) + octokit (4.2.0) + sawyer (~> 0.6.0, >= 0.5.3) + public_suffix (1.5.3) + rb-fsevent (0.9.7) + rb-inotify (0.9.7) + ffi (>= 0.5.0) + rdiscount (2.1.8) + redcarpet (3.3.3) + rouge (1.10.1) + safe_yaml (1.0.4) + sass (3.4.21) + sawyer (0.6.0) + addressable (~> 2.3.5) + faraday (~> 0.8, < 0.10) + terminal-table (1.5.2) + thread_safe (0.3.5) + typhoeus (0.8.0) + ethon (>= 0.8.0) + tzinfo (1.2.2) + thread_safe (~> 0.1) + +PLATFORMS + ruby + +DEPENDENCIES + github-pages + jekyll + +BUNDLED WITH + 1.11.2 +``` + +You can always delete the Gemlock file and run Bundle install again to get the latest versions. You can also run `bundle update`, which will ignore the Gemlock file to get the latest versions of each gem. + +To learn more about Bundler, see [Bundler's Purpose and Rationale](http://bundler.io/rationale.html). + diff --git a/mydoc/mydoc_collections.md b/mydoc/mydoc_collections.md index a157cfe..27eb323 100644 --- a/mydoc/mydoc_collections.md +++ b/mydoc/mydoc_collections.md @@ -1,6 +1,6 @@ --- title: Collections -tags: [content-types] +tags: [content_types] keywords: groups, api, structure last_updated: March 20, 2016 summary: "Collections are useful if you want to loop through a special folder of pages that you make available in a content API. You could also use collections if you have a set of articles that you want to treat differently from the other content, with a different layout or format." diff --git a/mydoc/mydoc_generating_pdfs.md b/mydoc/mydoc_generating_pdfs.md index 66da7a3..db3b88f 100644 --- a/mydoc/mydoc_generating_pdfs.md +++ b/mydoc/mydoc_generating_pdfs.md @@ -1,7 +1,7 @@ --- title: Generating PDFs permalink: /mydoc_generating_pdfs/ -tags: [publishing, single_sourcing, content-types] +tags: [publishing, single_sourcing, content_types] keywords: PDF, prince, prince XML, ant, xsl fo last_updated: March 20, 2016 summary: "You can generate a PDF from your Jekyll project. You do this by creating a web version of your project that is printer friendly. You then use utility called Prince to iterate through the pages and create a PDF from them. It works quite well and gives you complete control to customize the PDF output through CSS, including page directives and dynamic tags from Prince." diff --git a/mydoc/mydoc_help_api.md b/mydoc/mydoc_help_api.md index 7959e35..2c2e7d9 100644 --- a/mydoc/mydoc_help_api.md +++ b/mydoc/mydoc_help_api.md @@ -1,6 +1,6 @@ --- title: Help APIs and UI tooltips -tags: [publishing, single_sourcing, content-types] +tags: [publishing, single_sourcing, content_types] last_updated: March 20, 2016 keywords: API, content API, UI text, inline help, context-sensitive help, popovers, tooltips summary: "You can loop through files and generate a JSON file that developers can consume like a help API. Developers can pull in values from the JSON into interface elements, styling them as popovers for user interface text, for example. The beauty of this method is that the UI text remains in the help system (or at least in a single JSON file delivered to the dev team) and isn't hard-coded into the UI." diff --git a/mydoc/mydoc_install_jekyll_on_mac.md b/mydoc/mydoc_install_jekyll_on_mac.md index 3c35a10..f495b2a 100644 --- a/mydoc/mydoc_install_jekyll_on_mac.md +++ b/mydoc/mydoc_install_jekyll_on_mac.md @@ -9,34 +9,48 @@ permalink: /mydoc_install_jekyll_on_mac/ ## Ruby and RubyGems -Ruby and [RubyGems](https://rubygems.org/pages/download) are usually installed by default on Macs. Open your Terminal and type 'which ruby' and `which gem` to confirm that you have Ruby and Rubygems. You should get a response indicating the location of Rubygems, such as `/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem`. +Ruby and [RubyGems](https://rubygems.org/pages/download) are usually installed by default on Macs. Open your Terminal and type `which ruby` and `which gem` to confirm that you have Ruby and Rubygems. You should get a response indicating the location of Ruby and Rubygems. + +If you get responses that look like this: -However, you will likely run into permissions errors when executing from the operating system's version of Ruby. A sample error looks like this: +``` +/usr/local/bin/ruby +``` + +and + +``` +/usr/local/bin/gem +``` + +Great! Skip down to the [Bundler](#bundler) section. + +However, if your location is something like `/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem`, which points to your system location of Rubygems, you will likely run into permissions errors when trying to get a gem. A sample permissions error might look like this for Rubygems: ``` >ERROR: While executing gem ... (Gem::FilePermissionError) You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory. ``` -Instead of changing the write permissions on your OS's version of Ruby, you can install another instance of Ruby (one that is writable) to get around this. +Instead of changing the write permissions on your operating system's version of Ruby and Rubygems (which could pose security issues), you can install another instance of Ruby (one that is writable) to get around this. ## Install Homebrew -Homebrew is a package manager for the Mac, and you can use it to install alternative Ruby libraries. To install Homebrew, run this command: +Homebrew is a package manager for the Mac, and you can use it to install alternative Ruby code. To install Homebrew, run this command: ``` /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` -## Install Ruby through Homebrew - -If you already had Homebrew installed on your computer, first update it: +If you already had Homebrew installed on your computer, be sure to update it: ``` brew update ``` -Install Ruby through Homebrew: +## Install Ruby through Homebrew + +Now use Homebrew to install Ruby: ``` brew install ruby @@ -72,9 +86,9 @@ Then initialize rbenv: rbenv init ``` -If you still have issues, you need to resolve them before installing Bundler. +If you still have issues getting a writeable version of Ruby, you need to resolve them before installing Bundler. -## Install Bundler +

    Install Bundler

    At this point you should have a writeable version of Ruby on your machine. Now you need to get all the gems (or Ruby plugins) that you need for your Jekyll project. [Bundler](http://bundler.io/) is a package manager for RubyGems. @@ -88,7 +102,7 @@ If you're prompted to switch to superuser mode (`sudo`) to get the correct permi ## Customize the Gemfile -Bundler goes out and retreives all the gems that are specified in your project's Gemfile. If you have a gem that depends on other gems to work, Bundler will go out and retrieve all of the dependencies as well. (To learn more about Bundler, see {{site.data.urls.mydoc_about_ruby_gems_bundler.link}}. +Bundler goes out and retreives all the gems that are specified in your project's Gemfile. If you have a gem that depends on other gems to work, Bundler will go out and retrieve all of the dependencies as well. (To learn more about Bundler, see {{site.data.urls.mydoc_about_ruby_gems_etc.link}}. Open the Gemfile (in any text editor) in the Jekyll doc theme project: @@ -107,7 +121,7 @@ gem 'github-pages' gem 'jekyll' ``` -If you're publishing on Github Pages, leave the `github-pages` gem there. But if not, remove `github-pages` -- Github sometimes has dependencies that conflict with the latest versions of the Jekyll gem and Kramdown, which can be frustrating. +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. Use Bundler to install all the needed Ruby gems: diff --git a/mydoc/mydoc_install_jekyll_on_windows.md b/mydoc/mydoc_install_jekyll_on_windows.md index 8dbc452..5ba8b9c 100644 --- a/mydoc/mydoc_install_jekyll_on_windows.md +++ b/mydoc/mydoc_install_jekyll_on_windows.md @@ -5,52 +5,27 @@ keywords: jekyll on windows, pc, ruby, ruby dev kit sidebar: mydoc_sidebar --- -{% comment %} - -## Install Chocolately - -1. Go to **Start** and type **cmd**. -2. Right-click the Command Line Prompt and select **Run as Administrator.** -3. Copy the following code: - - ``` - @powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin - ``` -4. Right-click in the Command Line Prompt and select **Paste**. -5. Press **Enter**. -6. Close the Command Line Prompt. - -## Install Ruby - -1. Go to **Start** and type **cmd**. -2. Right-click the Command Line Prompt and select **Run as Administrator.** -3. Type the following: - - ``` - choco install ruby -y - ``` -3. Press **Enter**. -4. Close the Command Line Prompt. - -{% endcomment %} - {{site.data.alerts.tip}} For a better terminal emulator on Windows, download Console. This terminal allows you to create tabs and gives you more functionality. {{site.data.alerts.end}} ## Install Ruby +First you must install Ruby because Jekyll is a Ruby-based program and needs Ruby to run. + 1. Go to [RubyInstaller for Windows](http://rubyinstaller.org/downloads/). 2. Under **RubyInstallers**, download and install one of the Ruby installers (usually one of the first two options). 3. Double-click the downloaded file and proceed through the wizard to install it. ## Install Ruby Development Kit +Some extensions Jekyll uses require you to natively build the code using the Ruby Development Kit. + 1. Go to [RubyInstaller for Windows](http://rubyinstaller.org/downloads/). 2. Under the **Development Kit** section near the bottom, download one of the **For use with Ruby 2.0 and above...** options (either the 32-bit or 64-bit version). 3. Move your downloaded file onto your **C** drive in a folder called something like **RubyDevKit**. 4. Extract the compressed folder's contents into the folder. 5. Browse to the **RubyDevKit** location on your C drive using your Command Line Prompt. - {{site.data.alerts.tip}} To see the contents of your current directory, type dir. To drill into a directory, type cd foldername, where "foldername" is the name of the folder you want to enter. To move up a directory, type cd ../. To move into your user's directory, type /users.{{site.data.alerts.end}} + To see the contents of your current directory, type dir. To move into a directory, type cd foldername, where "foldername" is the name of the folder you want to enter. To move up a directory, type cd ../ one or more times depending on how many levels you want to move up. To move into your user's directory, type /users. The / at the beginning of the path automatically starts you at the root. 6. Type `ruby dk.rb init` 7. Type `ruby dk.rb install` @@ -72,9 +47,11 @@ If you get stuck, see the [official instructions for installing Ruby Dev Kit](ht This will create a new Gemfile. -4. Open the Gemfile in a text editor. You may need to use your File Explorer and browse to the directory, and then open the Gemfile in a text editor such as Notepad. +4. Open the Gemfile in a text editor. -5. Remove the existing contents and paste in the following: + Typically you can open files from the Command Prompt by just typing the filename, but because Gemfile doesn't have a file extension, no program will automatically open it. You may need to use your File Explorer and browse to the directory, and then open the Gemfile in a text editor such as Notepad. + +5. Remove the existing contents. Then paste in the following: ``` source "https://rubygems.org" @@ -82,12 +59,22 @@ If you get stuck, see the [official instructions for installing Ruby Dev Kit](ht gem 'wdm' gem 'jekyll' ``` + The [wdm gem](https://rubygems.org/gems/wdm/versions/0.1.1) allows for the polling of the directory and rebuilding of the Jekyll site when you make changes. This gem is needed for Windows users, not Mac users. + 6. Save and close the file. 7. Type `bundle install`. + + Bundle retrieves all the needed gems and gem dependencies and downloads them to your computer. At this time, Bundle also takes a snapshot of all the gems used in your project and creates a Gemfile.lock file to store this information. ## Serve the Jekyll site 1. Browse to the jekyll theme directory. 2. Type `jekyll serve` 3. Go to the preview address in the browser. (Make sure you include the `/` at the end.) + + Unfortunately, the Command Prompt doesn't allow you to easily copy and paste the URL, so you'll have to type it manually. + +## Troubleshooting + +Bundler retrieves the latest version of the jekyll gem that is compatible with the github-pages gem. Unfortunately, in my testing, I think that version of the jekyll gem has some issues with the kramdown gem. Later versions of the jekyll gem fix the kramdown compatibility issues. If you run into this issue, let me know (especially if you solved it). diff --git a/mydoc/mydoc_pages.md b/mydoc/mydoc_pages.md index 2ac9b07..7bf503e 100644 --- a/mydoc/mydoc_pages.md +++ b/mydoc/mydoc_pages.md @@ -1,6 +1,6 @@ --- title: Pages -tags: [getting_started, formatting, content-types] +tags: [getting_started, formatting, content_types] keywords: pages, authoring, exclusion, frontmatter last_updated: March 20, 2016 summary: "This theme primarily uses pages. You need to make sure your pages have the appropriate frontmatter. One frontmatter tag your users might find helpful is the summary tag. This functions similar in purpose to the shortdesc element in DITA." diff --git a/mydoc/mydoc_posts.md b/mydoc/mydoc_posts.md index 36489b9..7d52cf8 100644 --- a/mydoc/mydoc_posts.md +++ b/mydoc/mydoc_posts.md @@ -1,6 +1,6 @@ --- title: Posts -tags: [getting_started, formatting, content-types] +tags: [getting_started, formatting, content_types] keywords: posts, blog, news, authoring, exclusion, frontmatter last_updated: Feb 25, 2016 summary: "You can use posts when you want to create blogs or news type of content." diff --git a/mydoc/mydoc_series.md b/mydoc/mydoc_series.md index 8fef2f2..5b97537 100644 --- a/mydoc/mydoc_series.md +++ b/mydoc/mydoc_series.md @@ -1,6 +1,6 @@ --- title: Series -tags: [content-types] +tags: [content_types] keywords: series, connected articles, tutorials, hello world last_updated: March 20, 2016 summary: "You can automatically link together topics belonging to the same series. This helps users know the context within a particular process." diff --git a/tags/tag_content_types.html b/tags/tag_content_types.html index 8c4a637..effb7d6 100644 --- a/tags/tag_content_types.html +++ b/tags/tag_content_types.html @@ -1,6 +1,6 @@ --- title: "Content types pages" -tagName: content-types +tagName: content_types search: exclude permalink: /tag_content_types/ sidebar: tags_sidebar