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.
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.
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
Environment variables can be assigned as values in the configuration
file using the !ENV tag. Resolves#1954.
The behavior is defined in the third-party package pyyaml_env_tag:
https://github.com/waylan/pyyaml-env-tag
Replace vendored (and modified) copy of ghp_import with dependency on
upstream library. As of version 1.0+ ghp_import includes a Python API.
MkDocs can now benefit from recent bug fixes and new features, including the following:
* A `.nojekyll` file is automatically included when deploying to GitHub Pages.
* The `--shell` flag is now available, which reportedly works better on Windows.
* Git author and committer environment variables should be respected.
Resolves#2170 and resolves#1383.
We already link to the Deploying for Docs page which includes specific
instructions for various hosts. There is no need to also link to those
hosts in the Getting Started guide.
Closes#2210, closes#2104, closes#1890.
All IP addresses passed to `dev_addr` are now normalized.
`127.000.000.001` is normalized to `127.0.0.1`.
With apologies to docker container users, the address `0.0.0.0`
no longer raises an error but a warning instead. Apparently,
docker containers need to use that address, even in dev environments.
Closes#2108.
Travis only gives us Node.js version 8 so we must use an older
version of markdownlint. To declare a newer node.js version we
lose the ability to have Python as the lang and install tox.
If/when the default node version gets updated, remove the
version restriction on markdownlint.
Every call to `server.watch` requires `builder` to be passed in. If
users are to add their own watched files, then they need access to
`builder`. Fixes#1952.
Lunr.py version 0.5.8 maintains compatability with Lunr.js 2.3.8, but
restricts its dependnecy to nltk>=3.2.5,<3.5, which avoids installation
issues on some Docker images. Fixes#2062.
MkDocs has never supported using the included server for production.
However, some users have been using it that way. This would prevent that.
We also actually validate IP addresses now.
