The result is exactly equivalent, just different syntax -- one that doesn't look weird in vanilla Markdown parsers such as on GitHub.
The output HTML before/after is equivalent , other than adding `<p class="admonition-title">Block</p>` in two cases, which I hid with CSS.
This also contributes to fixing the currently-present markdownlint MD053 violations, as it can't scan inside admonitions.
Add 'markdown-callouts' to dependencies and bump Markdown dep.
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.
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.
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.
