New flag serve --open to open the site in a browser

After the first build is finished, the default webbrowser will open the home page of the site.

mkdocs/__main__.py

@@ -113,6 +113,7 @@ def __del__(self):
 serve_port_help = (
     "Port to serve documentation locally (default: 8000). Overrides the port from dev_addr."
 )
+serve_open_help = "Open the website in a Web browser when the first build finishes."
 strict_help = "Enable strict mode. This will cause MkDocs to abort the build on any warnings."
 theme_help = "The theme to use when building your documentation."
 theme_choices = sorted(utils.get_theme_names())
@@ -253,6 +254,7 @@ def cli():
 @cli.command(name="serve")
 @click.option('-a', '--dev-addr', help=dev_addr_help, metavar='IP:PORT')
 @click.option('-p', '--port', type=int, help=serve_port_help)
+@click.option('-o', '--open', 'open_in_browser', help=serve_open_help, is_flag=True)
 @click.option('--no-livereload', 'livereload', flag_value=False, help=no_reload_help)
 @click.option('--livereload', 'livereload', flag_value=True, default=True, hidden=True)
 @click.option('--dirtyreload', 'build_type', flag_value='dirty', hidden=True)

mkdocs/commands/serve.py

@@ -33,6 +33,7 @@ def serve(
     watch: list[str] = [],
     *,
     port: int | None = None,
+    open_in_browser: bool = False,
     **kwargs,
 ) -> None:
     """
@@ -123,7 +124,7 @@ def error_handler(code) -> bytes | None:
                 server.watch(item)
 
         try:
-            server.serve()
+            server.serve(open_in_browser=open_in_browser)
         except ServerBindError as e:
             log.error(f"Could not start a server on port {port}: {e}")
             msg = diagnose_taken_port(port, url=server.url, origin_info=origin_info)

mkdocs/livereload/__init__.py

@@ -19,6 +19,7 @@
 import time
 import traceback
 import urllib.parse
+import webbrowser
 import wsgiref.simple_server
 import wsgiref.util
 from typing import Any, BinaryIO, Callable, Iterable, Mapping
@@ -173,7 +174,7 @@ def unwatch(self, path: str) -> None:
             self._watched_paths.pop(path)
             self.observer.unschedule(self._watch_refs.pop(path))
 
-    def serve(self):
+    def serve(self, *, open_in_browser=False):
         try:
             self.server_bind()
         except OSError as e:
@@ -186,8 +187,13 @@ def serve(self):
             paths_str = ", ".join(f"'{_try_relativize_path(path)}'" for path in self._watched_paths)
             log.info(f"Watching paths for changes: {paths_str}")
 
-        log.info(f"Serving on {self.url}")
+        if open_in_browser:
+            log.info(f"Serving on {self.url} and opening it in a browser")
+        else:
+            log.info(f"Serving on {self.url}")
         self.serve_thread.start()
+        if open_in_browser:
+            webbrowser.open(self.url)
 
         self._build_loop()
 

mkdocs/tests/cli_tests.py

@@ -22,6 +22,7 @@ def test_serve_default(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -55,6 +56,7 @@ def test_serve_dev_addr(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr='0.0.0.0:80',
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -73,6 +75,7 @@ def test_serve_strict(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -93,6 +96,7 @@ def test_serve_theme(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -113,6 +117,7 @@ def test_serve_use_directory_urls(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -133,6 +138,7 @@ def test_serve_no_directory_urls(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -151,6 +157,7 @@ def test_serve_livereload(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,
@@ -169,6 +176,7 @@ def test_serve_no_livereload(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=False,
             build_type=None,
             config_file=None,
@@ -187,6 +195,7 @@ def test_serve_dirtyreload(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type='dirty',
             config_file=None,
@@ -205,6 +214,7 @@ def test_serve_watch_theme(self, mock_serve):
         mock_serve.assert_called_once_with(
             dev_addr=None,
             port=None,
+            open_in_browser=False,
             livereload=True,
             build_type=None,
             config_file=None,