This relimplements #1272 on the current code in master. Thanks to
@funkyfuture for the original work on this.
Also removes some unused code after #1504.
Closes#1272.
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.
Note that the icons in the themes will not show up until FontAwesome is
updated to at least version 4.6 and/or an up-to-date version of the
upstream readthedocs css is imported.
This commit also fixes a slight documentation error regarding the
default value of `repo_name` and removes some tautological tests.
* 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).
Present the sections in a logical manner:
1. File Layout (where to save documents)
* Configure Navigation...
2. Writing with Markdown
* Supported extensions...
Added documentation for all included extensions. Also added some basic
information about Markdown; pointing to the implementation and rules.
Fixes#1385, fixes#316, and fixes#1172.
Added theme customization settings to the search plugin:
* include_search_page: Determines whether the search plugin expects the
theme to provide a dedicated search page via a template located at
`search/search.html`.
* search_index_only: Determines whether the search plugin should only
generate a search index or a complete search solution.
Themes should define these settings in their `mkdocs_theme.yml` config file.
Documentation has been updated as well. Fixes#1315.
Note: while we would not normally add new settings (features) in a point
(bugfix) release, this is fixing a regression for third party themes.
Therefore, it is a "bugfix" and appropriate for a point release.
When serving locally, the `site_url` actually is the `dev_addr`, so the
config should relfect that. Note that this override must happen after
config validation so that the proper defaults are evaluated for the
`dev_addr` setting. It cannot happen as part of "post_validation" as
there is no way to know the dev server is running within the config
validation (for example, the dev_addr may not be None as the user could
have set the `dev_addr` setting in their config file). Overriding it
from the serve command is the least invasive method and guarantees it
only happens when the local dev server is being run.
Also cleaned up `dev_addr` docs, which were missleading in some respects
and actually encouraged using the dev server over a network.
Fixes#1317. 404 Error pages now work on the loval dev server when
the `site_url` in the config points to a subdir.
* Improve documentation and ensure it matches actual behavior.
* Use `page.edit_url` not `config.edit_url` in mkdocs template (opps).
* Include whitespace between icon and label in mkdocs theme.
* Undefined `edit_uri` results in `page.edit_url = None` when not automated.
* Setting `edit_uri: ''` disables automatic edit_uri for GitHub & Bitbucket.
Theme shows either a repo link or an edit link depending on whether
`edit_uri` is set. Also clarified documentation that this behavior is
dependant upon theme support. Fixes#1129.
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
Themes now have `theme` objects, and theme specific configs.
Themes can inherit from other themes. Users (and theme authors)
can define custom static templates and variables.
As neither setting can point at a child dir of the other, "/" would be an
invalid value for either setting. However, given its unique nature,
os.path.abspath does not follow normal bahavior of returning a string without
an ending slash when passed "/". Therefore, we need to special case it.
Fixes#1161.
Any template variables which mirrored a config setting have been deprecated
and should be accessed via the coresponding config template variable.
This resolves the rest of #874.
Some scripts need to execute after the page has finished loading.
To ensure that, the `scripts` block is placed at the bottom of the page.
However, if a user embeds scrpts within the body, and those scripts
rely in libs, then the libs need to already be loaded. By having
`libs` be a seperate block at the top of the page (int he header),
we can ensure that will work.
And we still want the libs in a block so a user can override them,
or even add to them (via `{{ super() }}`).
Fixes#956
