Document SITE_URL vs. BASE_URL better.

[aknrdureegaesr]

Requested Feature: (short description)

Somewhere in the documentation, I would like to see an example where

• BASE_URL and SITE_URL are configured differently
• The documentation explains which of the two is used for what.

Related Area: (eg. tasks, compilers, configuration, templates…)

I have seen code at nikola/nikola.py, which has a method url_replacer. When absolute URIs are to be constructed by that method, it constructs those relative to BASE_URL. So I conclude: BASE_URL is the URI that an external HTTP client would use to find the blog.

On the other hand, I have found code in the RobotsFile plugin task's class. That checks whether SITE_URL ist the URI of the root of some server. If that is not the case, the robots.txt - generation is understood to be meaningless. From this, I conclude that SITE_URL is the URI that an external HTTP client would use to find the blog.

The documentation in conf.py.in says:

# This is the main URL for your site. It will be used
# in a prominent link. Don't forget the protocol (http/https)!
SITE_URL = ${SITE_URL}
# This is the URL where Nikola's output will be deployed.
# If not set, defaults to SITE_URL
# BASE_URL = ${SITE_URL}

From that documentation, my initial understanding of this was that SITE_URL is some https:// URI where clients find my blog, whereas BASE_URL might be something like rsync:// that is used only internally. After looking through the code, this understanding clearly does not correspond to what is actually happening.

Do you want to contribute this yourself as a pull request? (don’t worry about it if you don’t want to/can’t — someone else can take care of it)

• Yes, I have already written code for it (link if available and feasible)
• Yes, I don’t have code ready yet (that’s okay!)
• No (that’s okay too!)

Would be "yes" if that was explained to me - but that explanation could as well be done via a code change rather than via personal communication. So I don't think it makes much sense to put me in as an intermediate between whoever knows and the code.

Does this feature affect backwards compatibility? If yes, in what way?

No. Only documentation is requested. (My confusion may stem from a bug/confusion in the Nikola code, fixing which could affect backwards compatibility.)

Rationale and full description: (why should it be added to Nikola?)

The present state is confusing. Improving the documentation would be an improvement of Nikola. Or, if there is no reason to differentiate the two, we should clean this up.

Real life story: I've already wasted a few hours trying to find the truth about this in the code. After that time, I have a strong feeling this should be explained plainly and easy to read in the documentation. Others may have the same problem.

[aknrdureegaesr]

I checked the output of

git diff 5.3 5.4

Apparently, at 5.3 and before, there was a single unified variable BLOG_URL, afterwards, two variables, namely the present SITE_URL and BASE_URL. Looking at the change as it happened did not help lift my confusion.

[aknrdureegaesr]

Digging further, the pertinent commit seems to be fb7cc87.