diff --git a/app/controllers/apitome/docs_controller.rb b/app/controllers/apitome/docs_controller.rb
index 0a1796f..043d4b1 100644
--- a/app/controllers/apitome/docs_controller.rb
+++ b/app/controllers/apitome/docs_controller.rb
@@ -37,7 +37,7 @@ def simulate
     def file_for(file, readme: false)
       if Apitome.configuration.remote_url
         file = readme ? file : "#{Apitome.configuration.doc_path}/#{file}"
-        file = URI.encode("#{Apitome.configuration.remote_url}/#{file}")
+        file = CGI.escape("#{Apitome.configuration.remote_url}/#{file}")
       else
         file = Apitome.configuration.root.join(Apitome.configuration.doc_path, file)
         raise Apitome::FileNotFoundError.new("Unable to find #{file}") unless File.exist?(file)
diff --git a/app/helpers/apitome/docs_helper.rb b/app/helpers/apitome/docs_helper.rb
index c98ff61..0dec6f1 100644
--- a/app/helpers/apitome/docs_helper.rb
+++ b/app/helpers/apitome/docs_helper.rb
@@ -6,11 +6,11 @@ def format_scope(scopes)
   end
 
   def resource_link(resource)
-    "#{Apitome.configuration.mount_at}/#{resource['examples'].first['link'].gsub(/\.json$/, '')}"
+    "#{Apitome.configuration.mount_at}/#{CGI.escape(resource['examples'].first['link'].gsub(/\.json$/, ''))}"
   end
 
   def example_link(example)
-    "#{Apitome.configuration.mount_at}/#{example['link'].gsub(/\.json$/, '')}"
+    "#{Apitome.configuration.mount_at}/#{CGI.escape(example['link'].gsub(/\.json$/, ''))}"
   end
 
   def link_active?(link)
diff --git a/spec/dummy/doc/api/access_tokens/user_access_token_(password).json b/spec/dummy/doc/api/access_tokens/user_access_token_[password].json
similarity index 98%
rename from spec/dummy/doc/api/access_tokens/user_access_token_(password).json
rename to spec/dummy/doc/api/access_tokens/user_access_token_[password].json
index 315aa70..b0f3736 100644
--- a/spec/dummy/doc/api/access_tokens/user_access_token_(password).json
+++ b/spec/dummy/doc/api/access_tokens/user_access_token_[password].json
@@ -2,7 +2,7 @@
   "resource": "Access Tokens",
   "http_method": "POST",
   "route": "/api/oauth/token",
-  "description": "User access token (password)",
+  "description": "User access token [password]",
   "explanation": "Most API endpoints require a user access token (e.g. for a user to be authenticated). This is similar to the\n[client access token](#access-tokens-client-access-token-client-credentials-), but requires the user credentials\nto be provided for one to be granted.\n\nIf an invalid/expired token is provided to any API endpoint, a 401 status code is returned, at which time a new\ntoken should be requested [using the refresh token](#access-tokens-user-access-token-refresh-token-) as returned\nhere.\n\nStoring the refresh token on the client is recommended for retrieving a new access token, and user credentials\nshould not be stored on the client. If authenticating via the refresh token fails, the user should be signed out\nand displayed a sign in view -- their user account may have been locked out, or your client credentials revoked.",
   "parameters": [
     {
diff --git a/spec/dummy/doc/api/index.json b/spec/dummy/doc/api/index.json
index c57edc6..1b57d95 100644
--- a/spec/dummy/doc/api/index.json
+++ b/spec/dummy/doc/api/index.json
@@ -9,8 +9,8 @@
           "groups": "all"
         },
         {
-          "description": "User access token (password)",
-          "link": "access_tokens/user_access_token_(password).json",
+          "description": "User access token [password]",
+          "link": "access_tokens/user_access_token_[password].json",
           "groups": "all"
         },
         {