Some of the docs were accidentally reverted with other things, so I'm restoring them and adding a bit more.
Fixing an edge case: it is in fact possible to specify a URL with scheme and without netloc. Adding new tests to also catch that.
This reverts commit b89ec5792e.
That commit claims to fix some bugs in interactions with `use_directory_urls`, but in fact there are currently no known unfixed bugs.
So there is no need to have that breaking change.
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.
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.
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.
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
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.
Despite Bootswatch not supporting nested dropdowns, the theme-specific CSS for
the mkdocs theme does add support for it, so we can remove the warning from
the release notes.
This patch improves the consistency of TOC levels, so now the level is always
equal to the N in the `<hN>` tag. It also allows users of the MkDocs theme to
set the navigation depth to show in the TOC panel (defaulting to 2).
Resolves#1910 and resolves#770.
* Disable Linkchecker Test.
* Switch to unittest.mock in standard lib.
* Apply `pyupgrade --py3-plus`.
* Note: Using `builtins.open` mocks all calls to `open`, including test setup
(such as in `load_config`). Whereas, `path.to.namespace.open` only mocks
`open` in that namepsace. This all worked differently when we used `io.open`
as that wasn't a builtin to begin with.
* Add a helpful error msg for PY2 users who use non-standard install methods.
Closes#1926.
This only updates the documentation to better reflect actual behavior.
The config for `theme.custom_dir` is defined in the `theme` config
option of `mkdocs.yml`. Therefore, any `mkdocs_theme.yml` file within
a custom_dir is ignored.
Fixes#588 and fixes#1374.
# Some implementation notes:
## `include_homepage_in_sidebar` setting
Note that the homepage is always linked from the site_name above the
search box. Therefore it does not need to also be in the nav tree.
In the upstream Sphinx theme, this is controlled when defining the
toctree. However, Sphinx has a separate setting for identifying the
"homepage". In MkDocs the homepage is identified as the first item in
the `nav`. Therefore, without this setting you can't exclude the
homepage from the sidebar like you can in Sphinx. With this setting we
get feature parity.
## Nested sections
This output is a little weird as the section title is a link that does
nothing when you click it. You need to click the `+` to expand the
submenu. But that is what the upstream theme requires to work.
