"One-time events" `on_startup(command)`, `on_shutdown`.
Their presence also shows that a plugin *wants* to persist across builds. Otherwise they will be re-created, to not change any existing behavior.
- Replaced some `.format` calls with f-strings.
- Removed `'r'` mode argument for `open` function as it is uneeded.
- Removed `__future__` import and `coding: utf-8` comment from a file.
* 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.
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.
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).
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.
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.
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.
Each version of lunr.py only works with a specific version of lunr.js.
Therefore we must hardcode the specific version of lunr.py in our
requirements. As we recently updated to lunr.js version 2.3.8 (#1995),
that coincides with lunr.py version 0.5.6. See the lunr.py CHANGELOG for
coinciding versions: https://github.com/yeraydiazdiaz/lunr.py/blob/master/CHANGELOG.md
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.
Internal handling of pages, files and navigation has been completely refactored.
The changes included in the refactor are summarized below.
* Support for hidden pages. All Markdown pages are now included in the build
regardless of whether they are included in the navigation configuration
(fixes#699).
* The navigation can now include links to external sites (fixes#989, fixes#1373,
& fixes#1406).
* Page data (including titles) is properly determined for all pages before any
page is rendered (fixes#1347).
* Automatically populated navigation now sorts index pages to the top. In other
words, The index page will be listed as the first child of a directory, while
all other documents are sorted alphanumerically by file name after the index
page (fixes#73 & fixes#1042).
* A `README.md` file is now treated as an index file within a directory and
will be rendered to `index.html` (fixes#608).
* The URLs for all files are computed once and stored in a files collection.
This ensures all internal links are always computed correctly regardless of
the configuration. This also allows all internal links to be validated, not
just links to other Markdown pages. (fixes#842 & fixes#872).
* An `on_files` plugin event has been added, which could be used to include
files not in the `docs_dir`, exclude files, redefine page URLs (i.e.
implement extensionless URLs), or to manipulate files in various other ways.
Backward incompatible changes are highlighted in the release notes included
with this commit. Some notes regarding various decisions follow in no particular
order:
This started out as the contents of the 'structure' dir from @tomchristie's
work in #689.
All paths must be all Unicode all the time. When a byte string and a
Unicode string are both passed to os.path (join ect) then returned value
is always a byte string. Therefore, we need every path string to be
Unicode. This ensures validation checks that and if the byte string uses
the file system encoding, decodes it. For any other encoding, a
validation error is raised.
Paths which start with a slash are assumed to be relative to the
docs_dir root. This behavior fixes#192. However, the slash not being
present in the output may surprise some users who are trying to create a
link relative to the server root when the mkdocs root is not at the
server root. The URLs available on a page are:
* Page.url is the url relative to the site_dir
* Page.canonical_url is the relative url joined with site_url or None if
site_url is not defined (the default).
* Page.abs_url is the path component of the canonical url or None if
canonical_url is None.
Note that new behavior is slightly different than before. Previously
abs_url ignored site_url and was always url with '' prepended. With the
new behavior, if site_url includes a subdir, that subdir will be
included in the abs_url.
When not on a server, there is no sensable "absolute_url" for a page.
Therefore, we shouldn't try to define one.
The thinking is that users generating docs to be browsed in the local
file system (`file://`) should leave the site_url setting unset, while
users who will be serving their docs from a server should be setting the
site_url. And if the site_url point sot a subdir of the server, the
abs_url will stil be absolute from the server root as it uses the "path"
of the canonical_url of the page.
Note that without the magical url context all URLs must be prepended by
`{{ base_url }}/` in the templates. While this requires a change in
third party themes, it is more consistent.
Links being ignored in raw HTML is now documented. Fixes#991.
All related tests that require temp dirs use the `mkdocs.tests.base.tempdir`
decorator. Note that any unrelated tests have not yet been updated.
That can happen separately from this. The one test in
`mkdocs.tests.structure.page_tests` (test_BOM) is unique enough to
not use the decorator.
* Use a web worker in the browser with a fallback (fixes#859 & closes#1396).
* Optionally pre-build search index (fixes#859 & closes#1061).
* Upgrade to lunr.js 2.x (fixes#1319).
* Support search in languages other than English (fixes#826).
* Allow the user to define the word separators (fixes#867).
* Only run searches for queries of length > 2 (fixes#1127).
* Remove dependency on require.js, mustache, etc. (fixes#1218).
* Compress the search index (fixes#1128).
Maintains better backward-compatability. Documentation updated, including
how to override the default. Also renamed the entry_point to 'search'.
The lib is still 'legacy_search'. When a new/better search plugin is
developed, the `search` entry_point will be pointed there so the default
behavior will inlcude the upgrade and a new `entry_point` will be added
('legacy_search') which points to the old plugin for those who really want
it.
See the included documentation for a full explanation of the API.
Search has been removed and wrapped in a plugin (named "legacy_search").
The search feature was ported as-is. None of the open issues with search
have been addressed. Presumably, a new search plugin will be built from
the ground up which addresses those issues.
Note that there is no 'default' plugins. That means that users get no
search unless they enable it in the config by adding the following to
their `mkdocs.yml` file:
plugins:
- legacy_search
Fixes#206
This change removes the dependency on mkdocs-bootstrap and mkdocs-bootswatch.
It also updates all references in the code. The only remaining connection is
when a user specifies one of these themes but they are not installed they get
slightly helpful error.
