Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
GitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
Just a warning to anyone who might want to change their project build directory to the root of the project, with a .yml file like this:
site_name: My Docs site_dir: / pages: - Home: index.md theme: material
It won't do what you think it will. If you run
Time to reformat. :D
I think you would need to set it to
I'd accept a change that warned users and forced them to type continue or something similar
In config validation, the first thing we generally do after confirming it is a string, is pass the value to
Although, I'm surprised the site_dir-can't-be-in-docs_dir and docs_dir-can't-be-in-site_dir checks didn't catch this. If one of them is at the system root, then the other must be in a subdir (of some level).
The general use case is that all local paths in the config file are expected to be relative to the location of the config file. I guess we just assume that everyone would always use relative paths. However, there may be a valid usecase for a user to use an absolute path, so we probably should issue a warning (and require explicit verification) before proceeding when an absolute path is provided. Something like:
A warning without the explicit verification is not of much value as the damage will already be started by the time the user sees the warning. Of course, with explicit verification, we would need to also provide a CLI flag to bypass the check for those users who need to automate with an absolute value.
The docs_dir-can't-be-in-site_dir check didn't catch it because we do:
if (config['docs_dir'] + os.sep).startswith(config['site_dir'] + os.sep):
And while removing the
Perhaps the fix here would be to just do
As neither setting can point at a child dir of the other, "/" would be an invalid value for either setting. However, given its unique nature, os.path.abspath does not follow normal bahavior of returning a string without an ending slash when passed "/". Therefore, we need to special case it. Fixes mkdocs#1161.
As neither setting can point at a child dir of the other, "/" would be an invalid value for either setting. However, given its unique nature, os.path.abspath does not follow normal bahavior of returning a string without an ending slash when passed "/". Therefore, we need to special case it. Fixes #1161.
Given the serious nature of this bug (destructive), I just pushed out a new release (0.16.2) after fixing it.
@welkie sorry for the problems. That never should have passed validation, and in fact it didn't before #1011. In any event, we have specific tests for it now.