diff --git a/Gemfile b/Gemfile index 4cbae70..bf4e6d9 100644 --- a/Gemfile +++ b/Gemfile @@ -1,4 +1,3 @@ -# A sample Gemfile source "https://rubygems.org" # gem "rails" diff --git a/_data/mydoc_urls.yml b/_data/mydoc_urls.yml index e7cf525..a07ecfe 100644 --- a/_data/mydoc_urls.yml +++ b/_data/mydoc_urls.yml @@ -9,112 +9,68 @@ +mydoc_hompepage: + 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/" + link: "5.0 Release notes" - - - -home: +mydoc_introduction: title: "Introduction" - url: "mydoc/home.html" - link: "Introduction" + url: "/documentation-theme-jekyll/mydoc_introduction/" + link: "Introduction" mydoc_supported_features: title: "Supported features" - url: "mydoc/mydoc_supported_features.html" - link: "Supported features" + url: "/documentation-theme-jekyll/mydoc_supported_features/" + link: "Supported features" mydoc_about: title: "About the theme author" - url: "mydoc/mydoc_about.html" - link: "About the theme author" + url: "/documentation-theme-jekyll/mydoc_about/" + link: "About the theme author" mydoc_support: title: "Support" - url: "mydoc/mydoc_support.html" - link: "Support" + url: "/documentation-theme-jekyll/mydoc_support/" + link: "Support" -mydoc_getting_started: - title: "1. Build the default project" - url: "mydoc/mydoc_getting_started.html" - link: "1. Build the default project" +mydoc_about_ruby_gems_etc: + title: "About Ruby, Gems, Bundler, etc." + url: "/documentation-theme-jekyll/mydoc_about_ruby_gems_etc/" + link: "About Ruby, Gems, Bundler, etc." -mydoc_adding_new_projects: - title: "2. Add a new project" - url: "mydoc/mydoc_adding_new_projects.html" - link: "2. Add a new project" +mydoc_install_jekyll_on_mac: + title: "Install Jekyll on Mac" + url: "/documentation-theme-jekyll/mydoc_install_jekyll_on_mac/" + link: "Install Jekyll on Mac" -mydoc_decide_on_attributes: - title: "3. Decide on your project's attributes" - url: "mydoc/mydoc_decide_on_attributes.html" - link: "3. Decide on your project's attributes" - - - -mydoc_configuration_settings: - title: "4. Set the configuration options" - url: "mydoc/mydoc_configuration_settings.html" - link: "4. Set the configuration options" - - - -mydoc_conditions_file_customization: - title: "5. Customize the conditions file" - url: "mydoc/mydoc_conditions_file_customization.html" - link: "5. Customize the conditions file" - - - -mydoc_configure_sidebar: - title: "6. Configure the sidebar" - url: "mydoc/mydoc_configure_sidebar.html" - link: "6. Configure the sidebar" - - - -mydoc_top_navigation: - title: "7. Configure the top navigation" - url: "mydoc/mydoc_top_navigation.html" - link: "7. Configure the top navigation" - - - -mydoc_url_generator_customization: - title: "8. Customize the URL generator" - url: "mydoc/mydoc_url_generator_customization.html" - link: "8. Customize the URL generator" - - - -mydoc_princexml_setup: - title: "9. Set up Prince XML" - url: "mydoc/mydoc_princexml_setup.html" - link: "9. Set up Prince XML" - - - -mydoc_build_scripts: - title: "10. Configure the build scripts" - url: "mydoc/mydoc_build_scripts.html" - link: "10. Configure the build scripts" +mydoc_install_jekyll_on_windows: + title: "Install Jekyll on Windows" + url: "/documentation-theme-jekyll/mydoc_install_jekyll_on_windows/" + link: "Install Jekyll on Windows" @@ -122,36 +78,43 @@ mydoc_build_scripts: mydoc_pages: title: "Pages" - url: "mydoc/mydoc_pages.html" - link: "Pages" + url: "/documentation-theme-jekyll/mydoc_pages/" + link: "Pages" + + + +mydoc_posts: + title: "Posts" + url: "/documentation-theme-jekyll/mydoc_posts/" + link: "Posts" mydoc_webstorm_text_editor: title: "WebStorm Text Editor" - url: "mydoc/mydoc_webstorm_text_editor.html" - link: "WebStorm Text Editor" + url: "/documentation-theme-jekyll/mydoc_webstorm_text_editor/" + link: "WebStorm Text Editor" mydoc_conditional_logic: title: "Conditional logic" - url: "mydoc/mydoc_conditional_logic.html" - link: "Conditional logic" + url: "/documentation-theme-jekyll/mydoc_conditional_logic/" + link: "Conditional logic" mydoc_content_reuse: title: "Content reuse" - url: "mydoc/mydoc_content_reuse.html" - link: "Content reuse" + url: "/documentation-theme-jekyll/mydoc_content_reuse/" + link: "Content reuse" mydoc_collections: title: "Collections" - url: "mydoc/mydoc_collections.html" - link: "Collections" + url: "/documentation-theme-jekyll/mydoc_collections/" + link: "Collections" @@ -159,29 +122,29 @@ mydoc_collections: mydoc_sidebar_navigation: title: "Sidebar navigation" - url: "mydoc/mydoc_sidebar_navigation.html" - link: "Sidebar navigation" + url: "/documentation-theme-jekyll/mydoc_sidebar_navigation/" + link: "Sidebar navigation" mydoc_yaml_tutorial: title: "YAML tutorial in the context of Jekyll" - url: "mydoc/mydoc_yaml_tutorial.html" - link: "YAML tutorial in the context of Jekyll" + url: "/documentation-theme-jekyll/mydoc_yaml_tutorial/" + link: "YAML tutorial in the context of Jekyll" -tags: +mydoc_tags: title: "Tags" - url: "mydoc/tags.html" - link: "Tags" + url: "/documentation-theme-jekyll/mydoc_tags/" + link: "Tags" mydoc_series: title: "Series" - url: "mydoc/mydoc_series.html" - link: "Series" + url: "/documentation-theme-jekyll/mydoc_series/" + link: "Series" @@ -189,71 +152,64 @@ mydoc_series: mydoc_adding_tooltips: title: "Tooltips" - url: "mydoc/mydoc_adding_tooltips.html" - link: "Tooltips" + url: "/documentation-theme-jekyll/mydoc_adding_tooltips/" + link: "Tooltips" mydoc_alerts: title: "Alerts" - url: "mydoc/mydoc_alerts.html" - link: "Alerts" + url: "/documentation-theme-jekyll/mydoc_alerts/" + link: "Alerts" mydoc_icons: title: "Icons" - url: "mydoc/mydoc_icons.html" - link: "Icons" + url: "/documentation-theme-jekyll/mydoc_icons/" + link: "Icons" mydoc_images: title: "Images" - url: "mydoc/mydoc_images.html" - link: "Images" + url: "/documentation-theme-jekyll/mydoc_images/" + link: "Images" mydoc_labels: title: "Labels" - url: "mydoc/mydoc_labels.html" - link: "Labels" + url: "/documentation-theme-jekyll/mydoc_labels/" + link: "Labels" mydoc_hyperlinks: title: "Links" - url: "mydoc/mydoc_hyperlinks.html" - link: "Links" + url: "/documentation-theme-jekyll/mydoc_hyperlinks/" + link: "Links" mydoc_navtabs: title: "Navtabs" - url: "mydoc/mydoc_navtabs.html" - link: "Navtabs" - - - -mydoc_video_embeds: - title: "Video embeds" - url: "mydoc/mydoc_video_embeds.html" - link: "Video embeds" + url: "/documentation-theme-jekyll/mydoc_navtabs/" + link: "Navtabs" mydoc_tables: title: "Tables" - url: "mydoc/mydoc_tables.html" - link: "Tables" + url: "/documentation-theme-jekyll/mydoc_tables/" + link: "Tables" mydoc_syntax_highlighting: title: "Syntax highlighting" - url: "mydoc/mydoc_syntax_highlighting.html" - link: "Syntax highlighting" + url: "/documentation-theme-jekyll/mydoc_syntax_highlighting/" + link: "Syntax highlighting" @@ -261,8 +217,8 @@ mydoc_syntax_highlighting: mydoc_commenting_on_files: title: "Commenting on files" - url: "mydoc/mydoc_commenting_on_files.html" - link: "Commenting on files" + url: "/documentation-theme-jekyll/mydoc_commenting_on_files/" + link: "Commenting on files" @@ -270,78 +226,71 @@ mydoc_commenting_on_files: mydoc_build_arguments: title: "Build arguments" - url: "mydoc/mydoc_build_arguments.html" - link: "Build arguments" + url: "/documentation-theme-jekyll/mydoc_build_arguments/" + link: "Build arguments" mydoc_themes: title: "Themes" - url: "mydoc/mydoc_themes.html" - link: "Themes" - - - -mydoc_link_validation: - title: "Link validation" - url: "mydoc/mydoc_link_validation.html" - link: "Link validation" + url: "/documentation-theme-jekyll/mydoc_themes/" + link: "Themes" mydoc_title_checker: title: "Check page title consistency" - url: "mydoc/mydoc_title_checker.html" - link: "Check page title consistency" + url: "/documentation-theme-jekyll/mydoc_title_checker/" + link: "Check page title consistency" mydoc_generating_pdfs: title: "Generating PDFs" - url: "mydoc/mydoc_generating_pdfs.html" - link: "Generating PDFs" - - - -mydoc_excluding_files: - title: "Excluding files" - url: "mydoc/mydoc_excluding_files.html" - link: "Excluding files" + url: "/documentation-theme-jekyll/mydoc_generating_pdfs/" + link: "Generating PDFs" mydoc_help_api: title: "Help APIs and UI tooltips" - url: "mydoc/mydoc_help_api.html" - link: "Help APIs and UI tooltips" + url: "/documentation-theme-jekyll/mydoc_help_api/" + link: "Help APIs and UI tooltips" mydoc_search_configuration: title: "Search configuration" - url: "mydoc/mydoc_search_configuration.html" - link: "Search configuration" + url: "/documentation-theme-jekyll/mydoc_search_configuration/" + link: "Search configuration" mydoc_iterm_profiles: title: "iTerm profiles" - url: "mydoc/mydoc_iterm_profiles.html" - link: "iTerm profiles" + url: "/documentation-theme-jekyll/mydoc_iterm_profiles/" + link: "iTerm profiles" mydoc_push_build_to_server: title: "Pushing builds to server" - url: "mydoc/mydoc_push_build_to_server.html" - link: "Pushing builds to server" + url: "/documentation-theme-jekyll/mydoc_push_build_to_server/" + link: "Pushing builds to server" mydoc_no_password_prompts_scp: title: "Getting around the password prompts in SCP" - url: "mydoc/mydoc_no_password_prompts_scp.html" - link: "Getting around the password prompts in SCP" + url: "/documentation-theme-jekyll/mydoc_no_password_prompts_scp/" + link: "Getting around the password prompts in SCP" + + + +mydoc_publishing_github_pages: + title: "Publishing on Github Pages" + url: "/documentation-theme-jekyll/mydoc_publishing_github_pages/" + link: "Publishing on Github Pages" @@ -349,54 +298,22 @@ mydoc_no_password_prompts_scp: mydoc_kb_layout: title: "Knowledge-base layout" - url: "mydoc/mydoc_kb_layout.html" - link: "Knowledge-base layout" + url: "/documentation-theme-jekyll/mydoc_kb_layout/" + link: "Knowledge-base layout" -mydoc_scroll: - title: "Scroll layout" - url: "mydoc/mydoc_scroll.html" - link: "Scroll layout" - - - -mydoc_shuffle: - title: "Shuffle layout" - url: "mydoc/mydoc_shuffle.html" - link: "Shuffle layout" - - - -mydoc_faq: - title: "FAQ layout" - url: "mydoc/mydoc_faq.html" - link: "FAQ layout" - - - -glossary: +mydoc_glossary: title: "Glossary layout" - url: "mydoc/glossary.html" - link: "Glossary layout" + url: "/documentation-theme-jekyll/mydoc_glossary/" + link: "Glossary layout" - - -mydoc_algoliasearch: - title: "Configuring Algolia search" - url: "mydoc/mydoc_algoliasearch.html" - link: "Configuring Algolia search" - - - - - -mydoc_mercurial_collaboration: - title: "Mercurial notes and tips" - url: "mydoc/mydoc_mercurial_collaboration.html" - link: "Mercurial notes and tips" +mydoc_faq_layout: + title: "FAQ layout" + url: "/documentation-theme-jekyll/mydoc_faq_layout/" + link: "FAQ layout" @@ -404,15 +321,8 @@ mydoc_mercurial_collaboration: mydoc_troubleshooting: title: "Troubleshooting" - url: "mydoc/mydoc_troubleshooting.html" - link: "Troubleshooting" - - - -mydoc_install_dependencies: - title: "Adding all project dependencies" - url: "mydoc/mydoc_install_dependencies.html" - link: "Adding all project dependencies" + url: "/documentation-theme-jekyll/mydoc_troubleshooting/" + link: "Troubleshooting" @@ -420,51 +330,126 @@ mydoc_install_dependencies: mydoc_tag_archives_overview: title: "Tag archives overview" - url: "mydoc/mydoc_tag_archives_overview.html" - link: "Tag archives overview" + url: "/documentation-theme-jekyll/mydoc_tag_archives_overview/" + link: "Tag archives overview" -tag_getting_started: - title: "Getting started pages" - url: "mydoc/tag_getting_started.html" - link: "Getting started pages" - - tag_formatting: title: "Formatting pages" - url: "mydoc/tag_formatting.html" - link: "Formatting pages" + url: "/documentation-theme-jekyll/tag_formatting/" + link: "Formatting pages" tag_navigation: title: "Navigation pages" - url: "mydoc/tag_navigation.html" - link: "Navigation pages" + url: "/documentation-theme-jekyll/tag_navigation/" + link: "Navigation pages" tag_content_types: title: "Content types pages" - url: "mydoc/tag_content_types.html" - link: "Content types pages" + url: "/documentation-theme-jekyll/tag_content_types/" + link: "Content types pages" tag_publishing: title: "Publishing pages" - url: "mydoc/tag_publishing.html" - link: "Publishing pages" + url: "/documentation-theme-jekyll/tag_publishing/" + link: "Publishing pages" tag_special_layouts: title: "Special layout pages" - url: "mydoc/tag_special_layouts.html" - link: "Special layout pages" + url: "/documentation-theme-jekyll/tag_special_layouts/" + link: "Special layout pages" tag_collaboration: title: "Collaboration pages" - url: "mydoc/tag_collaboration.html" - link: "Collaboration pages" + url: "/documentation-theme-jekyll/tag_collaboration/" + link: "Collaboration pages" + + +tag_troubleshooting: + title: "Troubleshooting pages" + url: "/documentation-theme-jekyll/tag_troubleshooting/" + link: "Troubleshooting pages" + + + + + + + + + + + + + + + + + + + + +p1_landing_page: + title: "Product 1 home" + url: "/documentation-theme-jekyll/p1_landing_page/" + link: "Product 1 home" + + + +p1_sample1: + title: "Sample 1" + url: "/documentation-theme-jekyll/p1_sample1/" + link: "Sample 1" + + + +p1_sample2: + title: "Sample 2" + url: "/documentation-theme-jekyll/p1_sample2/" + link: "Sample 2" + + + +p1_sample3: + title: "Sample 3" + url: "/documentation-theme-jekyll/p1_sample3/" + link: "Sample 3" + + + + + +p1_sample4: + title: "Sample 4" + url: "/documentation-theme-jekyll/p1_sample4/" + link: "Sample 4" + + + +p1_sample5: + title: "Sample 5" + url: "/documentation-theme-jekyll/p1_sample5/" + link: "Sample 5" + + + +p1_sample6: + title: "Sample 6" + url: "/documentation-theme-jekyll/p1_sample6/" + link: "Sample 6" + + + +p1_sample7: + title: "Sample 7" + url: "/documentation-theme-jekyll/p1_sample7/" + link: "Sample 7" @@ -486,9 +471,119 @@ tag_collaboration: +p2_landing_page: + title: "Product 2 home" + url: "/documentation-theme-jekyll/p2_landing_page/" + link: "Product 2 home" + + + +p2_sample1: + title: "Sample 1" + url: "/documentation-theme-jekyll/p2_sample1/" + link: "Sample 1" + + + +p2_sample2: + title: "Sample 2" + url: "/documentation-theme-jekyll/p2_sample2/" + link: "Sample 2" + + + + + +p2_sample3: + title: "Sample 3" + url: "/documentation-theme-jekyll/p2_sample3/" + link: "Sample 3" + + + +p2_sample4: + title: "Sample 4" + url: "/documentation-theme-jekyll/p2_sample4/" + link: "Sample 4" + + + + + +p2_sample5: + title: "Sample 5" + url: "/documentation-theme-jekyll/p2_sample5/" + link: "Sample 5" + + + +p2_sample6: + title: "Sample 6" + url: "/documentation-theme-jekyll/p2_sample6/" + link: "Sample 6" + + + +p2_sample7: + title: "Sample 7" + url: "/documentation-theme-jekyll/p2_sample7/" + link: "Sample 7" + + + + + + + +news: + title: "News" + url: "news" + link: "News" + + + + + + + + + + + + + + + + + + + + +mydoc_introduction: + title: "Jekyll Documentation Theme" + url: "mydoc_introduction" + link: "Jekyll Documentation Theme" + + + +p1_landing_page: + title: "Product 1" + url: "p1_landing_page" + link: "Product 1" + + + +p2_landing_page: + title: "Product 2" + url: "p2_landing_page" + link: "Product 2" + + + + diff --git a/_data/sidebars/mydoc_sidebar.yml b/_data/sidebars/mydoc_sidebar.yml index 7c61738..7fe9eea 100644 --- a/_data/sidebars/mydoc_sidebar.yml +++ b/_data/sidebars/mydoc_sidebar.yml @@ -48,6 +48,22 @@ entries: url: /mydoc_support/ output: web, pdf + - title: Installation + output: web, pdf + items: + + - title: About Ruby, Gems, Bundler, etc. + url: /mydoc_about_ruby_gems_etc/ + output: web, pdf + + - title: Install Jekyll on Mac + url: /mydoc_install_jekyll_on_mac/ + output: web, pdf + + - title: Install Jekyll on Windows + url: /mydoc_install_jekyll_on_windows/ + output: web, pdf + - title: Authoring output: web, pdf @@ -217,14 +233,6 @@ entries: url: /mydoc_troubleshooting/ output: web, pdf - - title: Adding all project dependencies - url: /mydoc_install_dependencies/ - output: web, pdf - - - title: Install Jekyll on Windows - url: /mydoc_install_jekyll_on_windows/ - output: web, pdf - - title: Tag archives output: web items: diff --git a/_data/tags.yml b/_data/tags.yml index a7985f0..af48a82 100644 --- a/_data/tags.yml +++ b/_data/tags.yml @@ -7,4 +7,6 @@ allowed-tags: - single_sourcing - special_layouts - collaboration - - news \ No newline at end of file + - news + - troubleshooting + - mobile \ No newline at end of file diff --git a/_data/urls.yml b/_data/urls.yml index 5e8e608..3a00ce8 100644 --- a/_data/urls.yml +++ b/_data/urls.yml @@ -16,6 +16,7 @@ mydoc_homepage: + mydoc_release_notes_50: title: "5.0 Release notes" url: "/documentation-theme-jekyll/mydoc_release_notes_50/" @@ -53,6 +54,29 @@ mydoc_support: +mydoc_about_ruby_gems_etc: + title: "About Ruby, Gems, Bundler, etc." + url: "/documentation-theme-jekyll/mydoc_about_ruby_gems_etc/" + link: "About Ruby, Gems, Bundler, etc." + + + +mydoc_install_jekyll_on_mac: + title: "Install Jekyll on Mac" + url: "/documentation-theme-jekyll/mydoc_install_jekyll_on_mac/" + link: "Install Jekyll on Mac" + + + +mydoc_install_jekyll_on_windows: + title: "Install Jekyll on Windows" + url: "/documentation-theme-jekyll/mydoc_install_jekyll_on_windows/" + link: "Install Jekyll on Windows" + + + + + mydoc_pages: title: "Pages" url: "/documentation-theme-jekyll/mydoc_pages/" @@ -303,20 +327,6 @@ mydoc_troubleshooting: -mydoc_install_dependencies: - title: "Adding all project dependencies" - url: "/documentation-theme-jekyll/mydoc_install_dependencies/" - link: "Adding all project dependencies" - - - -mydoc_install_jekyll_on_windows: - title: "Install Jekyll on Windows" - url: "/documentation-theme-jekyll/mydoc_install_jekyll_on_windows/" - link: "Install Jekyll on Windows" - - - mydoc_tag_archives_overview: diff --git a/index.md b/index.md index 964de1d..441be7d 100644 --- a/index.md +++ b/index.md @@ -1,24 +1,20 @@ --- -title: Getting started +title: Getting started overview tags: [getting_started] sidebar: mydoc_sidebar type: homepage --- -These instructions will help you get started quickly with the theme. The other topics in this help provide additional information and notes about working with other aspects of this theme and Jekyll. +## Overview -## Make sure you can build a vanilla Jekyll site first - -To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/). If you're in Windows, you'll need to install Ruby and Ruby Dev Kit first. See {{site.data.urls.mydoc_install_jekyll_on_windows.link}} for details. +These 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. ## Build this theme -1. Download the theme from the [Github repo for the Jekyll doc theme](https://github.com/tomjohnson1492/documentation-theme-jekyll). -2. Delete the Gemfile and Gemfile.lock files in the theme (unless you're planning to publish on Github Pages. If that's the case, see Publishing on Github Pages). -3. Customize the values in the \_config.yml file following the documentation included in that file. -3. Build the site using the usual Jekyll command: `jekyll serve` +If you're used to running Jekyll sites, you can type the normal jekyll command, `jekyll serve`, to run this site. However, if you're a new Jekyll user or if you run into issues, see the following two topics: -For more information about build arguments in general with Jekyll, see {{site.data.urls.mydoc_build_arguments.link}}. +* {{site.data.urls.mydoc_install_jekyll_on_mac.link}} +* {{site.data.urls.mydoc_install_jekyll_on_windows.link}} ## Configure the sidebar diff --git a/mydoc/mydoc_about_ruby_gems_bundler.md b/mydoc/mydoc_about_ruby_gems_bundler.md new file mode 100644 index 0000000..2bd2fa3 --- /dev/null +++ b/mydoc/mydoc_about_ruby_gems_bundler.md @@ -0,0 +1,114 @@ +--- +title: About Ruby, Gems, Bundler, and other Prerequisites +tags: [getting_started, troubleshooting] +keywords: +summary: "Ruby is a programming language you must have on your computer in order to build Jekyll locally. Ruby has various gems (or plugins) that provide various functionality. Each Jekyll project usually requires certain gems." +sidebar: mydoc_sidebar +permalink: /mydoc_about_ruby_gems_etc/ +--- + +## About Ruby + +Jekyll runs on Ruby, a programming language. You have to have Ruby on your computer in order to run Ruby-based programs like Jekyll. Ruby is installed on the Mac by default, but you must add it to Windows. + +## 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. + +Some gems depend on other gems for functionality. For example, the Jekyll gem might depend on 20 other gems that must also be installed. + +Each gem has a version associated with it, and not all gem versions are compatible with each other. + +## 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. + +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: + +``` +github-pages-health-check = 1.1.0 +jekyll = 3.0.3 +jekyll-coffeescript = 1.0.1 +jekyll-feed = 0.4.0 +jekyll-gist = 1.4.0 +jekyll-github-metadata = 1.9.0 +jekyll-mentions = 1.1.2 +jekyll-paginate = 1.1.0 +jekyll-redirect-from = 0.10.0 +jekyll-sass-converter = 1.3.0 +jekyll-seo-tag = 1.3.2 +jekyll-sitemap = 0.10.0 +jekyll-textile-converter = 0.1.0 +jemoji = 0.6.2 +kramdown = 1.10.0 +liquid = 3.0.6 +mercenary ~> 0.3 +rdiscount = 2.1.8 +redcarpet = 3.3.3 +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. + +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/): + +> Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed. +> +> Bundler is an exit from dependency hell, and ensures that the gems you need are present in development, staging, and production. Starting work on a project is as simple as bundle install. + +## Gemfiles + +Bundler looks in a project's "Gemfile" (no file extension) to see which gems are required by the project. The Gemfile lists the source and then any gems, like this: + +``` +source "https://rubygems.org" + +gem 'github-pages' +gem 'jekyll' +``` + +The source indicates the site where Bundler will retrieve the gems: https://rubygems.org. + +The gems it retrieves are listed separately on each line. + +Here no versions are specified. Sometimes gemfiles will specify the versions like this: + +``` +gem 'kramdown', '1.0' +``` + +This means Bundler should get version 1.0 of the kramdown gem. + +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. + +Here it will get any gem equal to 2.3 but less than 3.0. + +If it adds another digit, the scope is affected: + +``` +gem `jekyll`, `~>2.3.1' +``` + +This means to get any gem equal to 2.3.1 but less than 2.4. + +If it looks like this: + +``` +gem 'jekyll', '~> 3.0', '>= 3.0.3' +``` + +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. + diff --git a/mydoc/mydoc_install_dependencies.md b/mydoc/mydoc_install_dependencies.md deleted file mode 100644 index a492249..0000000 --- a/mydoc/mydoc_install_dependencies.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Adding all project dependencies -tags: [getting-started, troubleshooting] -keywords: -summary: "You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects." -sidebar: mydoc_sidebar -permalink: /mydoc_install_dependencies/ ---- - -To manage the various gems and their versions needed for your project, you can use a package manager called Bundler. Many projects will have a gemfile in their project that lists the gems required for the project. You then run Bundler in order to automatically install the required gems and any dependencies for those gems on your machine. - -## RubyGems - -Make sure you have RubyGems. This should be installed by default on Mac. - -Open Terminal and type `which gem`. You should get a response indicating the location of Rubygems, such as `/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem`. - -If you need to install Rubygems, see [Download RubyGems](https://rubygems.org/pages/download). - -## Install Bundler - -[Bundler](http://bundler.io/) is a package manager for RubyGems. - -You install Bundler by using the gem command with RubyGems: - -``` -gem install bundler -``` - -If you're prompted to which to superuser mode (`sudo`) to get the correct permissions to install Bundler in that directory, avoid doing this. All other applications that need to use Bundler will likely not have the needed permissions to run. - - -If you get a permissions error when trying to install Bundler, use Homebrew to install a Ruby package manager called rbenv. - -Install Homebrew: - -``` -/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` - -Use brew to install rbenv: - -``` -brew install rbenv -``` - -Initialize rbenv: - -``` -rbenv init -``` - -Log out of terminal, and then then log back in. - -Install Bundler: - -``` -gem install bundler -``` - -Open the gemfile: - -``` -open gemfile -``` - -You should see some gems listed. If you don't have a gemfile, your project may not need any gems, or those gems may not be managed at the project level but rather directly installed manually. You can create a gemfile by typing `bundle init`. - -Your gemfile might look like this: - -``` -# A sample Gemfile -source "https://rubygems.org" - -# gem "rails" -gem 'github-pages' -gem 'pygments.rb' -gem 'redcarpet' -``` - -Use Bundler to install the needed gems: - -``` -bundle install -``` - -Finally, you can run the following to make sure the installed gems get associated or initialized with your project: - -``` -bundle exec jekyll serve -``` - -## Ruby permissions errors - -While trying to install a missing gem, you get an error message that says, - ->ERROR: While executing gem ... (Gem::FilePermissionError) - You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory. - -This most likely happens with El Capitan on the Mac. - -As long as you have brew installed (see the previous section), run the following: - -``` -brew update -brew install ruby -``` - -Close your terminal, and then restart a fresh session. - -Now run the gem you're trying to install, such as the following: - -``` -gem install kramdown -``` \ No newline at end of file diff --git a/mydoc/mydoc_install_jekyll_on_mac.md b/mydoc/mydoc_install_jekyll_on_mac.md new file mode 100644 index 0000000..3c35a10 --- /dev/null +++ b/mydoc/mydoc_install_jekyll_on_mac.md @@ -0,0 +1,122 @@ +--- +title: Install Jekyll on Mac +tags: [getting_started, troubleshooting] +keywords: +summary: "Installation of Jekyll on Mac is usually less problematic than on Windows. However, you may run into permissions issues with Ruby that you must overcome. You should also use Bundler to be sure that you have all the required gems and other utilities on your computer to make the project run. " +sidebar: mydoc_sidebar +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`. + +However, you will likely run into permissions errors when executing from the operating system's version of Ruby. A sample error looks like this: + +``` + >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. + +## 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: + +``` +/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: + +``` +brew update +``` + +Install Ruby through Homebrew: + +``` +brew install ruby +``` + +Log out of terminal, and then then log back in. + +When you type `which ruby` and `which gem`, you should get responses like this: + +``` +/usr/local/bin/ruby +``` + +And this: + +``` +/usr/local/bin/gem +``` + +Now Ruby and Rubygems are installed under your username, so these directories are writeable. + +Note that if you don't see these paths, try restarting your computer or try installing rbenv, which is a Ruby version management tool. + +You can install rbenv through Homebrew using this command: + +``` +brew install rbenv +``` + +Then initialize rbenv: + +``` +rbenv init +``` + +If you still have issues, you need to resolve them before installing 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. + +You install Bundler by using the gem command with RubyGems: + +``` +gem install bundler +``` + +If you're prompted to switch to superuser mode (`sudo`) to get the correct permissions to install Bundler in that directory, avoid doing this. All other applications that need to use Bundler will likely not have the needed permissions to run. + +## 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}}. + +Open the Gemfile (in any text editor) in the Jekyll doc theme project: + +``` +open Gemfile +``` + +The theme's gemfile looks as follows: + +``` +# A sample Gemfile +source "https://rubygems.org" + +# gem "rails" +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. + +Use Bundler to install all the needed Ruby gems: + +``` +bundle install +``` + +Now run Jekyll serve to build the theme: + +``` +jekyll serve +``` \ No newline at end of file diff --git a/mydoc/mydoc_install_jekyll_on_windows.md b/mydoc/mydoc_install_jekyll_on_windows.md index 37ac026..8dbc452 100644 --- a/mydoc/mydoc_install_jekyll_on_windows.md +++ b/mydoc/mydoc_install_jekyll_on_windows.md @@ -34,6 +34,7 @@ sidebar: mydoc_sidebar {% 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 @@ -44,29 +45,42 @@ sidebar: mydoc_sidebar ## Install 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. -3. Extract Ruby onto your **C** drive in a folder called something like **RubyDevKit**. -3. Browse to the **RubyDevKit** location on your C drive using your Command Line Prompt. -3. Type `ruby dk.rb init` -3. Type `ruby dk.rb install` +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}} + +6. Type `ruby dk.rb init` +7. Type `ruby dk.rb install` If you get stuck, see the [official instructions for installing Ruby Dev Kit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit). ## Install Bundler -1. In the downloaded theme, *delete* the existing **Gemfile** and **Gemfile.lock** files. -1. Type `gem install bundler`. -2. Browse to the documentation-jekyll-theme directory. -3. Type `bundle init` -4. Open the Gemfile in a text editor. -5. Paste in the following: +1. Using the command line, browse to the folder where you downloaded the Jekyll theme. +2. Delete the existing **Gemfile** and **Gemfile.lock** files: + + ``` + del Gemfile + del Gemfile.lock + ``` + +1. Install Bundler: `gem install bundler` +3. Initialize Bundler: `bundle init` + + 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. + +5. Remove the existing contents and paste in the following: ``` - # A sample Gemfile source "https://rubygems.org" - gem 'wdm', '>= 0.1.0' if Gem.win_platform? - gem 'jekyll', '~> 3.1', '>= 3.1.2' + gem 'wdm' + gem 'jekyll' ``` 6. Save and close the file. @@ -74,6 +88,6 @@ If you get stuck, see the [official instructions for installing Ruby Dev Kit](ht ## Serve the Jekyll site -1. Browse to the documentation-jekyll-theme directory. +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.)