From e9ea98678c8d19e14b7de406b6e01186058d4483 Mon Sep 17 00:00:00 2001
From: Max Vilimpoc <max@vilimpoc.org>
Date: Sat, 10 Mar 2018 23:42:29 -0600
Subject: [PATCH] Update windows.md to explain an issue with jekyll new.
 (#6838)

Merge pull request 6838
---
 docs/_docs/troubleshooting.md | 49 +++++++++++++++++++++++++++++++++++
 docs/_docs/windows.md         |  6 ++++-
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/docs/_docs/troubleshooting.md b/docs/_docs/troubleshooting.md
index 4ccc1643..55ece507 100644
--- a/docs/_docs/troubleshooting.md
+++ b/docs/_docs/troubleshooting.md
@@ -97,6 +97,55 @@ Xcode.app can interfere with the command line tools downloaded above. If
 you run into this issue, upgrade Xcode and install the upgraded Command
 Line Tools.
 
+### Running Jekyll as Non-Superuser (no sudo!) 
+{: #no-sudo}
+
+On most flavors of Linux, macOS, and Bash on Ubuntu on Windows, it is
+possible to run Jekyll as a non-superuser and without having to install
+gems to system-wide locations by adding the following lines to the end 
+of your `.bashrc` file:
+
+```sh
+# Ruby exports
+
+export GEM_HOME=$HOME/gems
+export PATH=$HOME/gems/bin:$PATH
+```
+
+This tells `gem` to place its gems within the user's home folder, 
+not in a system-wide location, and adds the local `jekyll` command to the 
+user's `PATH` ahead of any system-wide paths.
+
+This is also useful for many shared webhosting services, where user accounts
+have only limited privileges. Adding these exports to `.bashrc` before running 
+`gem install jekyll bundler` allows a complete non-`sudo` install of Jekyll.
+
+To activate the new exports, either close and restart Bash, logout and 
+log back into your shell account, or run `. .bashrc` in the 
+currently-running shell.
+
+If you see the following error when running the `jekyll new` command,
+you can solve it by using the above-described procedure:
+
+```
+$ jekyll new test
+Running bundle install in /home/user/test...
+
+
+Your user account isn't allowed to install to the system RubyGems.
+  You can cancel this installation and run:
+
+      bundle install --path vendor/bundle
+
+  to install the gems into ./vendor/bundle/, or you can enter your password
+  and install the bundled gems to RubyGems using sudo.
+
+  Password:
+```
+
+Once this is done, the `jekyll new` command should work properly for
+your user account.
+
 ### Jekyll &amp; Mac OS X 10.11
 
 With the introduction of System Integrity Protection, several directories
diff --git a/docs/_docs/windows.md b/docs/_docs/windows.md
index e0ca4d7b..b81c65c6 100644
--- a/docs/_docs/windows.md
+++ b/docs/_docs/windows.md
@@ -61,8 +61,12 @@ jekyll new my_blog
 
 You can make sure time management is working properly by inspecting your `_posts` folder. You should see a markdown file with the current date in the filename.
 
-**Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
+<div class="note info">
+  <h5>Non-superuser account issues</h5>
+  <p>If the `jekyll new` command prints the error "Your user account isn't allowed to install to the system RubyGems", see the "Running Jekyll as Non-Superuser" instructions in <a href="/docs/troubleshooting/#no-sudo">Troubleshooting</a>.</p>
+</div>
 
+**Note:** Bash on Ubuntu on Windows is still under development, so you may run into issues.
 
 [WSL-Guide]: https://msdn.microsoft.com/en-us/commandline/wsl/install_guide
 [BASH-WSL]: https://msdn.microsoft.com/en-us/commandline/wsl/about