Tighten the docs and tests around site_url (#2506)

Some of the docs were accidentally reverted with other things, so I'm restoring them and adding a bit more.

Fixing an edge case: it is in fact possible to specify a URL with scheme and without netloc. Adding new tests to also catch that.

docs/user-guide/configuration.md

@@ -28,13 +28,17 @@ variable.
 
 ### site_url
 
-Set the canonical URL of the site. This will add a link tag with the canonical
-URL to the generated HTML header.
+Set the canonical URL of the site. This will add a `link` tag with the
+`canonical` URL to the `head` section of each HTML page. If the 'root' of the
+MkDocs site will be within a subdirectory of a domain, be sure to include that
+subdirectory in the setting (`https://example.com/foo/`).
 
-If the built site will not be behind a server, then you may set the value to an
-empty string (`''`). When set to an empty string, some features of MkDocs may
-act differently. For example, the [use_directory_urls](#use_directory_urls)
-setting must be set to `false`.
+This setting is also used for `mkdocs serve`: the server will be mounted onto a
+path taken from the path component of the URL, e.g. `some/page.md` will be
+served from `http://127.0.0.1:8000/foo/some/page/` to mimick the expected remote
+layout.
+
+**default**: `null`
 
 ### repo_url
 
@@ -391,6 +395,8 @@ Allows a custom default to be set without the need to pass it through the
 
 **default**: `'127.0.0.1:8000'`
 
+See also: [site_url](#site_url).
+
 ## Formatting options
 
 ### markdown_extensions

mkdocs/config/config_options.py

@@ -301,7 +301,7 @@ def run_validation(self, value):
         except (AttributeError, TypeError):
             raise ValidationError("Unable to parse the URL.")
 
-        if parsed_url.scheme:
+        if parsed_url.scheme and parsed_url.netloc:
             if self.is_dir and not parsed_url.path.endswith('/'):
                 parsed_url = parsed_url._replace(path=f'{parsed_url.path}/')
             return urlunsplit(parsed_url)

mkdocs/tests/config/config_options_tests.py

@@ -280,39 +280,34 @@ def test_invalid_IPv6_address(self):
 class URLTest(unittest.TestCase):
 
     def test_valid_url(self):
+        option = config_options.URL()
 
-        url = "https://mkdocs.org"
+        self.assertEqual(option.validate("https://mkdocs.org"), "https://mkdocs.org")
+        self.assertEqual(option.validate(""), "")
 
-        option = config_options.URL()
-        value = option.validate(url)
-        self.assertEqual(value, url)
+    def test_valid_url_is_dir(self):
+        option = config_options.URL(is_dir=True)
 
-    def test_invalid_url(self):
+        self.assertEqual(option.validate("http://mkdocs.org/"), "http://mkdocs.org/")
+        self.assertEqual(option.validate("https://mkdocs.org"), "https://mkdocs.org/")
 
+    def test_invalid_url(self):
         option = config_options.URL()
+
         self.assertRaises(config_options.ValidationError,
                           option.validate, "www.mkdocs.org")
+        self.assertRaises(config_options.ValidationError,
+                          option.validate, "//mkdocs.org/test")
+        self.assertRaises(config_options.ValidationError,
+                          option.validate, "http:/mkdocs.org/")
+        self.assertRaises(config_options.ValidationError,
+                          option.validate, "/hello/")
 
-    def test_invalid(self):
-
+    def test_invalid_type(self):
         option = config_options.URL()
         self.assertRaises(config_options.ValidationError,
                           option.validate, 1)
 
-    def test_url_is_dir(self):
-        url = "https://mkdocs.org/"
-
-        option = config_options.URL(is_dir=True)
-        value = option.validate(url)
-        self.assertEqual(value, url)
-
-    def test_url_transform_to_dir(self):
-        url = "https://mkdocs.org"
-
-        option = config_options.URL(is_dir=True)
-        value = option.validate(url)
-        self.assertEqual(value, f'{url}/')
-
 
 class RepoURLTest(unittest.TestCase):