New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use use_directory_urls: false breaks on empty site_url #2189
Comments
The HMTL fragment in the report is from mkdocs/mkdocs/themes/mkdocs/base.html Line 66 in ff0b726
With best intentions, I think this could be fixed in the
|
This is indeed a bug of MkDocs which should be fixed. We also had this problem as part of Material for MkDocs, which I was able to mitigated with squidfunk/mkdocs-material@454339b – just in case you're using this template. Other than that, the commit may be helpful for other theme devs. |
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter (... | url). NOTE: Some values to the filter are declared undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter (... | url). NOTE: Some values to the filter are declared undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter (... | url). NOTE: Some values to the filter are declared undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter ( {{ ... | url }} ). NOTE: Some values to the filter are declared undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
Given the reliance on |
Wouldn't that break local browsing? Some users of Material for MkDocs build their docs and distribute the resulting It's great to see you're back, @waylan! |
That is a potential concern; except that we have never officially supported local file browsing. For the I should note that any of the existing solutions for local file browsing are hacks by users. While I don't see a need to break those hacks unnecessarily, any new official way to support such a feature is not likely to work well with the existing hacks. Finally, the elephant in the room is the builtin search plugin, which does not work with local file browsing and the primary reason why we do not officially support the option. IIRC, the Material theme doesn't have that limitation, but we would need to address that before any official support exists. That said, any changes to the plugin should be discussed in a separate issue. At a minimum, if All of the above are just ideas. I havn't looked at the feasibility of any of them. I'm just thinking out load here. |
That got me thinking... What if we just changed the default of The one concern here is that there is a distinct difference in output between |
Material relies on mkdocs-localsearch and iframe-worker to support search on
Hard to say whether that won't break anything. It's only another default, so it can be overridden, but it may result in confusion for users. I'd like to get @wilhelmer in the loop because he's the own maintaining the localsearch plugin. Another idea: site_url: null |
I just looked at those for the first time. At a glance, I don't see any reason why that wouldn't work with other themes with a couple minor tweeks. Still, it seems like a lot of work for the user (overriding template blocks) just to enable local file browsing. I wonder if perhaps mkdocs-localsearch could be merged with the search plugin. In fact, before looking at it, I assumed it would be a replacement for the search plugin, not an additional plugin which works beside it. In any event, that is a discussion for a different issue. So far we have three proposed values for I also have some reservations about |
In order for search to work locally, the Furthermore, if search is implemented as part of a web worker, the |
This is the reason why I'm not a fan of |
Yeah, let's abandon the |
I just checked and the default value for
Assuming a user has an existing project and has not defined either setting, upon upgrading to the new version of MkDocs, she would get the warning discussed in 2 above. She could simply ignore the warning and the existing behavior would continue. However, she would want to avoid any future updates. On the other hand, if, in an effort to avoid the warning, she then sets For a new user who first creates a project with the new version of MkDocs, the generated config file would include an entry for But what is a sensible default to put in the generated config file of a new project? We can't explicitly set the value to Therefore, we could insert an example domain, such as And the documentation for both settings should link to each other and explain the interaction between them. We would include instructions specifically for how to enable local file browsing which explains that both settings need to be set and what values they should be set to. Finally, note that in this proposal, no defaults have been changed for any settings. I initially started to write this proposal with the idea that the default value for |
I don't feel I'm proficient enough in the internal mechanics of MkDocs to decide whether that covers all cases, but it sounds good to me in general. In essence, we have three cases that should be covered:
However, there might be cases where people don't set the |
A minor grip:
I'll assume you mean people might want to set Note that my solution to this issue ( |
That is only a concern because we don't offer an official way to define multiple deployments within a config. Therefore, users who want that have come up with various hacks. Note my proposal in #2218 which is intended to provide an official option. Of course, please keep discussions about #2218 in that issue. I only mention it here to note that if we implemented a solution to #2218, it would remove that as a blocker for this issue. Especially as it seems that that is the only cited reason to not make |
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter ( {{ ... | url }} ). NOTE: Some values to the filter are undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter ( {{ ... | url }} ). NOTE: Some values to the filter are undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
Previously when "use_directory_urls" was false and "site_url" empty (e.g. documentation for fs), the link to the home-page / main index was broken missing /index.html at the end of the url. Fix is to add the missing index.html in such a case by the url-template- filter ( {{ ... | url }} ). NOTE: Some values to the filter are undefined behavior as the filter will return wrong urls. These cases are considered theoretical (a file-name must end with a dot and be at the end of value) and not likely to happen. Declaring them undefined now, allows to change the implementation later in a compatible way.
I have problems to follow this prolonged discussion but would like to bring things forward in a constructive manner. Who needs to make what kind of design decision? Answers to that question would help me to continue with this work. |
In the end, I can still implement my proposal with one change: A null value is not permitted for |
As long as the built documentation can still be browsed offline and the concerns in #2189 (comment) are nullified, I'm happy with anything that you come up with. You know the inner workings of MkDocs much better than me. Thanks for your work! |
The site_url config option is now required. If it is set to an empty string, then use_directory_urls will be forced to false. Each will issue a warning if not properly set. In a future release we may raise an error instead. Fixes mkdocs#2189.
The site_url config option is now required. If it is set to an empty string, then use_directory_urls will be forced to false. Each will issue a warning if not properly set. In a future release we may raise an error instead. Fixes #2189.
Is there a way to set the site_url with the command line? |
yes, via the
unstable: if the file grows, mkdocs might become more picky and then requires a regular file (needs seek). a temporary file then should do it (e.g. mind the docs_dir if not specified within the file. (comment against mkdocs version 1.1.2) |
In the 1.2 release (which will require a site_url) the easiest way to do this would be through an environment variable, which is another new feature of 1.2. See more here. First, use the site_url: !ENV [SITE_URL, https://fallback.com] Then on the commandline do: SITE_URL="https://example.com" mkdocs build |
May I ask why you need the complete url of the website to build the documentation website? If I could do site_url: / I could upload the same build on different hosts if it was possible. The current error I get when I have this error logged:
NB: I ask about this here because it's the issue where it was discussed to make |
mkdocs/mkdocs#2189 ```text WARNING - Config value: 'site_url'. Warning: This option is now required. Set to a valid URL or an empty string to avoid an error in a future release. ```
#34 36eca9d a877045 https://www.mkdocs.org/user-guide/configuration/#site_url https://www.mkdocs.org/user-guide/configuration/#use_directory_urls mkdocs/mkdocs#2189 mkdocs/mkdocs#2360 https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ squidfunk/mkdocs-material#2520 MkDocs recently made the `site_url` setting required. A warning is now seen when `site_url` is not included in mkdocs.yml: ```text WARNING - Config value: 'site_url'. Warning: This option is now required. Set to a valid URL or an empty string to avoid an error in a future release. ``` The docs describe the `site_url` setting as follows: > Set the canonical URL of the site. This is a required setting. 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 domain is yet to be determined, you > may use a placeholder domain, which will need to be updated prior to > deployment. > > 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` setting must be set to false. If the docs are "behind a server," they often have more than one URL. Which should be set as the `site_url`? Furthermore, if the related `use_directory_urls` is set to `true`, it appends a trailing slash to the URLs generated for the ToC (Table of Contents). This commit will set `site_url: ""` and `use_directory_urls: false`. In combination with the `{"cleanUrls": true, "trailingSlash": false}` settings in vercel.json, the previous behavior of URLs and navigation will be restored.
#1 br3ndonland/inboard#34 br3ndonland/inboard@9943112 https://www.mkdocs.org/user-guide/configuration/#site_url https://www.mkdocs.org/user-guide/configuration/#use_directory_urls mkdocs/mkdocs#2189 mkdocs/mkdocs#2360 https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ squidfunk/mkdocs-material#2520 MkDocs recently made the `site_url` setting required. A warning is now seen when `site_url` is not included in mkdocs.yml: ```text WARNING - Config value: 'site_url'. Warning: This option is now required. Set to a valid URL or an empty string to avoid an error in a future release. ``` The docs describe the `site_url` setting as follows: > Set the canonical URL of the site. This is a required setting. 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 domain is yet to be determined, you > may use a placeholder domain, which will need to be updated prior to > deployment. > > 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` setting must be set to false. If the docs are "behind a server," they often have more than one URL. Which should be set as the `site_url`? Furthermore, if the related `use_directory_urls` is set to `true`, it appends a trailing slash to the URLs generated for the ToC (Table of Contents). This commit will set `site_url: ""` and `use_directory_urls: false`. In combination with the `{"cleanUrls": true, "trailingSlash": false}` settings in vercel.json, the previous behavior of URLs and navigation will be restored.
I intend to revisit (i.e. likely revert) the decision to make |
@oprypin Can you add some context? As long as it transparently works, I'm not against it (as I had the reported case). Currently it is "patched" in the theme and when it became mandatory, I was injecting it IIRC, I have tooling around anyway so this was not that much of a deal for me personally. |
Well it's a big deal for me and at least some people Basically the argument is that a URL is not something inherent to a collection of documents. |
That sounds good to me. And yes, there was a fix, it's a bit older now, but from my end I gave it quite some love and testing. But mind, even I'm doing URL related stuff since quite a long time, I'm not at all that long familiar with mkdocs. So I guess the main decision reg. #2202 is likely a design decision how to handle this. And IIRC for #2202 I got tests running but I'm not fully confident my unit-test setup was right. And also part of the existing code perhaps was missing coverage and I added it, likely before the changes but it's perhaps worth to replay this. |
This comment has been minimized.
This comment has been minimized.
Nevermind, my comment is wrong. Looking at this commit squidfunk/mkdocs-material@454339b clarifies things more than any textual description :) |
I found that this issue was actually fixed by #2366, and neither #2202 nor #2405 are necessary. $ git checkout -f 1.1.2
$ echo $'site_url: null\nuse_directory_urls: false' >>mkdocs.yml; mkdocs build; grep 'navbar-brand' site/index.html site/about/license.html
site/index.html: <a class="navbar-brand" href=".">MkDocs</a>
site/about/license.html: <a class="navbar-brand" href="..">MkDocs</a>
$ git checkout -f d038223e7ab52ba6cd8890909d97645856ba6b31~
$ echo $'site_url: null\nuse_directory_urls: false' >>mkdocs.yml; mkdocs build; grep 'navbar-brand' site/index.html site/about/license.html
site/index.html: <a class="navbar-brand" href=".">MkDocs</a>
site/about/license.html: <a class="navbar-brand" href="..">MkDocs</a>
$ git checkout -f d038223e7ab52ba6cd8890909d97645856ba6b31
$ echo $'site_url: null\nuse_directory_urls: false' >>mkdocs.yml; mkdocs build; grep 'navbar-brand' site/index.html site/about/license.html
site/index.html: <a class="navbar-brand" href="index.html">MkDocs</a>
site/about/license.html: <a class="navbar-brand" href="../index.html">MkDocs</a> @ktomk Could you please |
@oprypin: If I finally manage to run a test ;), should I run it against master then? Or against the merge commit? |
@MathieuPuech Thanks for the suggestion #2189 (comment) |
For the file:// based static site I'm now using the material theme solution:
which works. I was not able to get it working with vanilla mkdocs config (e.g. empty |
When setting the
site_url
tonull
(default) anduse_directory_urls
isfalse
to make the docs browse-able in a user friendly fashion accessible from the local file-system, in the default mkdocs theme the link to the site on the site-name:is missing the
/index.html
added to the existing href.
(dot).The text was updated successfully, but these errors were encountered: