Livereload sometimes doesn't work without an internet connection

[blankoworld]

Last days I encount some network problems. It reveals a curious problem on mkdocs with readthedoc theme: the refresh after a change on a file don't give any result. How I reproduce it:

• I use a virtualenv with Python3
• I download mkdocs, version 0.15.3 with pip: pip install mkdocs
• I remove my network cable from the computer (I don't have any wifi stuff)
• I start a new project with mkdocs new superdoc
• I change mkdocs.yml to add this line:

theme: readthedocs

• I start the server with mkdocs serve -a localhost:8002
• Then I notice all is OK here: http://localhost:8002/
• I update docs/index.md with "Something" after the line "For full documentation visit [...]"
• On my webbrowser (Firefox 45.0), the page start being refreshed (a kind of circle is turning) but nothing more happens. I don't see my changes.

To my mind, as linking the network cable permits the refresh to be effective, I think that the page attempt to download something from the Internet during the refresh. For an example a font.
And as I see here: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/readthedocs/base.html#L18 it's probably the case.

Is that possible to include the font for the "readthedoc" theme, or adding download it during the "pip install" command? Or probably another similar font?

Thanks you in advance,

Olivier.

[waylan]

My initial reaction was to say that if you have downloaded the font once, then it should be cached locally, but then I remembered that caching will break if the browser can't actually access the server. After all, the browser needs to check with the server to make sure the local cache is still valid before using the locally cached copy.

So, I guess the question is whether we should be hosting the files locally or using Google's CDN (Content Delivery Network). There's a nice summary of the pros and cons of using a CDN here. When serving a MkDocs site live on the web, a CDN makes sense IMO. However, for obvious reasons, a CDN is not always the best option for development.

The tricky part is that we can't just download and commit one file and be done. Different browsers all require different font file formats and the CDN just serves the one for that browser (see this). If we included the font locally, we would have to download all of the formats and make sure they are all in sync (and again if/when we update later). And then there is the size issue. All those files really add up to quite a lot of space (relatively speaking). Sure, we already include the FontAwesome files locally, but that is a custom crafted set of files which include only a handful of characters, not an entire character set. There may also be licencing concerns... which I have not looked into at all.

[d0ugal]

I think we can consider this a limitation of the theme - they expect to be online. If there is a way we can better make it work when the fonts are unreachable (offline or the CDN is down) then we should do that.

[blankoworld]

Sorry to be a noob but: Why is Google font mandatory for this theme? Is there no other similar font on websites?

Is there no way to download the Google font during the pip install command?

It's very curious for me to expect having an Internet connection while you're writing documentation ^_^

[d0ugal]

Why is Google font mandatory for this theme? Is there no other similar font on websites?

Because that is the way it was done originally (over 2 years ago) and nobody has had the motivation to change it. So that is a huge number of users and this is the first report I am aware of.

The theme is ported from ReadTheDocs, we do so with minimal changes. I assume they also use Google Fonts but I've not looked in a long time.

Is there no way to download the Google font during the pip install command?

No, that would be the wrong place to do it I think. While technically possible it would be an abuse of Python packaging. We would likely need to store the files in git and manually manage them but then also give users the option of using the CDN. Quickly it becomes a non-trivial issue.

It's very curious for me to expect having an Internet connection while you're writing documentation ^_^

Have you tried using a different theme? Did you check for errors in the terminal?

From my testing it works fine, the font doesn't load and it looks a tiny bit different but it looks more than good enough for writing documentation. I suspect this is an incorrect diagnosis of the problem, I replicated all of your steps except I used Chrome (and I was on OSX, I'm not sure which OS you use) and everything worked fine.

[d0ugal]

... and just for completeness I went ahead and installed FireFox for you and tested with that to. It worked fine, just the same as Chrome. So I've re-titled this issue to reflect that.

So, there is something else here that is wrong or different between our environments. However, I can't think what. @blankoworld Can you try mkdocs serve --no-livereload and see if that helps?

[blankoworld]

I'm on Ubuntu 14.04.4 LTS.

I test without this line (in mkdocs.yml file):

theme: readthedocs

No problem appears. Seems that only appears with "readthedocs" theme.

I so check with/without --no-livereload option.

WITH nolivereload option:

WITHOUT nolivereload option:
(first display)

(after a reload)

It seems that it take a long time to download Google fonts. Then it gives up. In all cases.

I check the HTML code and see that:

<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>

I so check this link: https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700

You see some CSS. Is that not possible to copy this CSS into the HTML page?

I expect this CSS to attempt to download given fonts, then apply a default one (if remote ones not found). Did you think it's possible?

[d0ugal]

You see some CSS. Is that not possible to copy this CSS into the HTML page?

No, from what I understand, Google changes the response depending on the device and browser.

I expect this CSS to attempt to download given fonts, then apply a default one (if remote ones not found). Did you think it's possible?

I thought it already did do this, a default font is displayed for me when I am completely offline and use MkDocs.

[blankoworld]

I so don't know what I can do to avoid the problem on my side and find the way for you to reproduce it :-(.

[d0ugal]

That is a good question! I am not sure how to do that either. I'll give it some thought.

[waylan]

I'm closing this as a duplicate to #1138. I realize this is an older issue, but #1138 provides a more compelling use case for fixing it (using a CDN for font files can be broken on a live site, not just the dev server).