Restore the ability to watch files through relative symlinks
(i.e. symlinks that have a non-absolute path as the target)
This was not fully fixed in #2427.
Switch from os.path.realpath to pathlib.Path.resolve
A new replacement option (theme.analytics.gtag) was added to the built-in themes. Multiple different services could be offered under theme.analytics. At this time only support for gtag exists, but more could be added in the future.
Fixes#2252.
* Support dict only markdown_extensions config
* Support dict only plugin config
* Remove explicit conversion to Unicode as PY2 is no longer supported.
* Refactor yaml_load so that is can recursively call itself.
Fixes#2218.
Watchdog doesn't support it directly but it happened to work everywhere except Windows
This is achieved by walking through the target directory, finding any symlinks in it, and watching their target too (+recursive walking of those too).
Important note: only symlinks that exist during startup will be taken into account, new ones aren't added.
Fixes#2425Closes#2426
When `mkdocs serve` is shutting down, it cleans up after itself removing
the temporary directory created earlier.
Previously the condition whether the directory is to be removed was
unchecked and prone to a file system race condition (shared resource).
Given the directory is absent on the file-system while shutting down,
`mkdocs serve` threw an exception and exited in failure.
Change is to override the cause of the exception by preventing the
attempt to remove a directory that is already gone.
Closes#2420.
This discards the dependency on 'livereload' and 'tornado'. This implementation is based on stdlib http.server and is much smaller, while not being a downgrade in any way.
This fixes#2061: multiple file changes no longer cause the site to repeatedly rebuild.
It also makes reloads much more responsive; they're "instant" rather than being on a 1-second polling interval or such.
Each HTML page gets JavaScript injected into it (like before) but now, instead of connecting to WebSocket, it requests a long-polling endpoint, which blocks until a newer version ("epoch") of the site is available - then the page knows to reload itself. After a minute without events, the endpoint will just return the unchanged epoch (to avoid timeouts), then the page requests the same endpoint again. The "downtime" in between requests is not a problem because these are not events that need to be received in real time; the endpoint can instantly report that the latest version is newer than the one the page identified itself as.
The reason to replace WebSocket isn't that it's bad or something, just that stdlib doesn't have it. But long-polling works completely fine here too.
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.
A framework for translating themes as been added, which includes:
1. Use of Jinja's `i18n` plugin for translating phrases in templates (not page content).
2. A French translation of the built-in themes (contributions in other languages are welcome).
3. A new `theme.locale` option to define the locale/language of the site.
4. The search plugin uses the value of `theme.locale` as its default 'lang'.
5. Third party themes may chose to use the framework (use is optional).
6. A documented workflow for translating MkDocs built-in themes.
7. Custom tooling for use by translators and theme devs.
The dependencies are not installed by default and are not needed to use MkDocs without translations. However, for anyone who wants to make use of the features, `pip install mkdocs[i18n]` will install all necessary dependencies.
Relates to #211.
Closes#2177
* Instead of using nav items for sitemap entries rendering, `[file.page for file in pages]` is used.
* Rendered sitemap.xml content is properly formatted using 4 spaces for indentation.
The new ClickHandler was causing all log messages to be printed to the
test output. As it offered no real value and littered the test output,
we are reverting back to the logging.StreamHandler with no loss of
functionality. See #2364 for context.
Provide for better reporting to users, make for easier maintenance going forward, and allow future expandability. The following major changes were made:
1. The logging config is now defined in a way which will allow future expandability. For example, we could add additional levels of `strict` or `verbosity` (see #1756) . All log messages are fed to a single log, which has two handlers (one for strict mode and one for verbosity). All level restrictions are defined per handler so that one restriction does not interfere with another. As filters do not have a level assigned to them, the previous count filter is now a nullhandler which counts all messages is receives (restricted only by level). The previous filter still exists (as a do-nothing instance) for any third-party plugins which called it. Those plugins should remove the call going forward.
2. A new exception `mkdocs.exceptions.Abort` was added. Rather than calling `SystemExit`, we now call `Abort`, which is a custom `click` exception that aborts with a readable error message and no traceback. Where appropriate, we catch errors, log them, and then call `Abort`. This allows us to remove all error handling from the CLI code and include it where errors originate from. Of course, as previously, unanticipated errors will still generate a traceback to allow debugging.
3. Log formatting has been improved. All log messages are now hard wrapped and indented for easier reading and color is used to identify each by type. Note that colors are only used to highlight errors, warnings and debug messages. Under normal operation with no issues, the user will not see any color.
`urlparse(config['site_url']).path` can be empty if `site_url` does not end
in a slash. This ensures at least a slash is returned. Config validation
will add the slash if it is missing. Fixes#1785.
This reverts commit f73f221f1f.
It seems that the `wait` flag does not interupt the file watcher,
but simply delays builds. Therefore, a plugin which writes to the
`docs_dir` will still result in an infinite loop. That being the
case, the `wait` flag is not useful to us. See #2285.
Rather than including this is the JS form the upstream theme, the JS
has been included in a separate file `theme_extra.js` so that is is not
lost in a future update copied form upstream. Fixes#2028.
This is using the new "selection interface" ( by calling `entry_points` with
the `group` parameter) that is being introduced in `importlib.metadata` of
Python 3.10 (currently in alpha). While the backport (`importlib_metadata`)
introduced the same change in version 3.6, various improvements have been made
up through the current release (3.10). Therefore we require
`importlib_metadata>=3.10` for all supported versions of Python (3.6-3.9).
Replace the global variable `mkdocs.config.DEFAULT_SCHEMA` with
the function `mkdocs.config.defaults.get_schema()`. An instance is no
longer created on import (eliminating circular imports under certain
circumstances) and each call to `get_schema()` builds a new instance
of each object. Fixes#2289.
The homepage has been redesigned. The "Installation" and "Getting Started" sections were moved to their own respective pages. Then, the homepage was restyled so that the list of features appear as a grid of cards.
The developer specific pages were moved to a new section: `dev-guide`. Any old URLs redirect to the new ones.
When only one of the two passed paths starts with a slash, this function would produce results that depend on (and expose parts of) the actual current working directory.
In a similar manner, it was also possible to "break out" of the "current directory" by starting one of the paths with `../../..` etc.
Additionally, the fact that paths always end up being resolved relative to the current working directory made this function less efficient than it needs to be.
Fun fact: `get_relative_url('path_a', 'path_b')` actually ended up looking up how to get to `/current/working/directory/path_a` from `/current/working/directory/path_b`.
Luckily, none of these behaviors can ever actually come into effect (the function is always called without a leading slash and without paths deliberately trying to escape), but the fix is still good to reduce surprise.
*The actual fix* is that we make the leading slash ignored (or quite the opposite - we always add it).
Now when either of the two arguments try to go up higher than the top level, they just end up at the top level (e.g. `foo/../..` is effectively `.`), only then the "relative" calculation happens.
Improve readme with a different structure and some link changes.
The landscape.io links have been removed as that project seems
discontinued since April 2020.
With `long_description_content_type="text/markdown"` it is possible
to use Markdown text in the `long_description` meta-data field. Make sure
the latest tools (setuptools, wheel, twine) are installed before deploying.
Plugins wishing to manipulate the Files structure have an append
method but can't dynamically work on src_paths since it's computed
once on Files instanciation
This commits allows plugins to manipulate Files trough append and
remove of file objects while not having to care about the src_paths
since it's now a dynamically computed property
When a parameter value validation fails for a plugin the name of
the failing plugin is not displayed
This commit adds the name of the plugin in the error message for
completeness
