Enhance `mkdocs serve` behavior? #3494

fralau · 2023-12-02T09:03:12Z

fralau
Dec 2, 2023

Unsurprisingly, mkdocs serve is one of the most frequently used commands with MkDocs.

There are are two improvements I would like to see:

Start the default browser. That seems a reasonable approach, as done by Jupyter for example.
If the default port is taken, don't fail; just take the next one.

I haven't made a survey, but I suppose that a good 80% of the users would be happy with that evolution, out of the box.

There might always be a number who do not like it, for legitimate reasons (it would be good to list those objections, to understand how to answer them). To avoid taking risks I would be happy with the following approach:

Initially, make the new behavior optional (opt-in), with a parameter in the config file
Then see how it goes, and if it seems a good idea, make it standard.
But if there the slightest doubt, allow an opt-out in the config file.

What would you think?

oprypin · 2023-12-02T09:08:12Z

oprypin
Dec 2, 2023

These are good ideas. You could open an issue for each of them.
Regarding ports it'll need some discussion of details to not make it the port totally unpredictable

3 replies

oprypin Dec 2, 2023

I'll implement these

fralau Dec 2, 2023
Author

Opened:

Start the default browser, when starting the mkdocs serve command? #3495 for starting the default browser
With mkdocs serve switch to another port if the current port is busy #3496 for port switching

oprypin Dec 2, 2023

Opened pull request:

Enhance serve: randomize the port, allow to open a browser #3497

pawamoy · 2023-12-02T10:06:30Z

pawamoy
Dec 2, 2023

Not a fan of automatically opening the URL in the browser. First because I use different browser profiles and it probably won't use the right one, and second because even if it got the right profile, I don't want it to reopen the same tab each time I interrupt and re-run mkdocs serve. If it can detect that the URL is already open in a tab, then that would be best. Anyway, I'm fine with either opt-in or opt-out 🙂

0 replies

squidfunk · 2023-12-02T14:28:51Z

squidfunk
Dec 2, 2023

I'm pretty sure this could be implemented in a plugin using the on_serve hook which is executed once the initial build is finished, and allows you to register additional logic when file changes are detected.

2 replies

fralau Dec 2, 2023
Author

This is an intriging idea. It could work, at least for starting the browser. 🤔

squidfunk Dec 2, 2023

Jup, the "choose another port" behavior might not be implementable, because on_startup doesn't receive the MkDocsConfig object, which is the only hook that one could use to dynamically change the dev_addr setting. Maybe this might be added to core, i.e., providing it as a third option to the hook.

mkdocs/mkdocs/commands/serve.py

Lines 56 to 69 in 646987d

    
           config = get_config() 
        
           config.plugins.on_startup(command=('build' if is_clean else 'serve'), dirty=is_dirty) 
        
           def builder(config: MkDocsConfig | None = None): 
        
               log.info("Building documentation...") 
        
               if config is None: 
        
                   config = get_config() 
        
               build(config, live_server=None if is_clean else server, dirty=is_dirty) 
        
           host, port = config.dev_addr 
        
           server = LiveReloadServer( 
        
               builder=builder, host=host, port=port, root=site_dir, mount_path=mount_path(config) 
        
           )

redtide · 2023-12-25T12:16:30Z

redtide
Dec 25, 2023

Start the default browser. That seems a reasonable approach, as done by Jupyter for example.

This sounds strange to me, why a page server should open a client? It seems to me so straightforward as is: start serving pages, click on the link that opens the browser (it's a user choice to do it or not). When restarting there is already livereload, which I would like to make optional but this is another thing, otherwise just press F5.

If the default port is taken, don't fail; just take the next one.

Until now I haven't miss this neither when using Jekyll, but I don't see why not having it as option (I mean, OK to me if will be part of mkdocs, but I would be against to have it enabled by default).
It could be implemented as a list of regexes maybe? So you can also choose the way it selects the port number.

0 replies

Uh oh!

Enhance mkdocs serve behavior? #3494

Uh oh!

Uh oh!

Replies: 4 comments · 5 replies

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fralau Dec 2, 2023 Author

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fralau Dec 2, 2023 Author

Uh oh!

Uh oh!

Enhance `mkdocs serve` behavior? #3494

Replies: 4 comments 5 replies

fralau Dec 2, 2023
Author

fralau Dec 2, 2023
Author