Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Internal Refactor of Pages, Files, and Navigation (mkdocs#1504)
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 mkdocs#699). * The navigation can now include links to external sites (fixes mkdocs#989, fixes mkdocs#1373, & fixes mkdocs#1406). * Page data (including titles) is properly determined for all pages before any page is rendered (fixes mkdocs#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 mkdocs#73 & fixes mkdocs#1042). * A `README.md` file is now treated as an index file within a directory and will be rendered to `index.html` (fixes mkdocs#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 mkdocs#842 & fixes mkdocs#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 mkdocs#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 mkdocs#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 mkdocs#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.
- Loading branch information
