Skip to content

mkdocs serve --livereload hangs, forces to CTRL-C and restart #3389

@squidfunk

Description

@squidfunk

Whenever we use mkdocs serve --livereload, the livereload server blocks, as MkDocs waits for changes to files that can be reported back to the browser. This technique is known as long polling, and albeit we now have wide support for websockets which are a superior solution, it's a perfectly fine implementation for livereload functionality.

Blocking is implemented here:

self._epoch_cond.wait_for(condition, timeout=self.poll_response_timeout)

However, sometimes when I navigate the site while working on it, MkDocs gets stuck in this condition and waits for changes to files. There are three ways to unblock it:

  1. Change and save a file, so MkDocs rebuilds it and returns it to the browser
  2. Press ESC in the browser to cancel the /livereload request
  3. Wait for a minute until it times out

I'm not very familiar with the livereload implementation, but the problem seems to be that the server is occupied with waiting for the livereload request to finish hitting one of the conditions mentioned above, which prohibits the navigation from happening – see the loading indicator after navigating for the third time:

Ohne.Titel.mov

My testing shows that this problem can be solved by cancelling the pending /livereload request before navigation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions