This is primarily to allow third party themes which inherit from the
mkdocs theme (such as the bootswatch themes) to alter the code
highlighting style. Previously all of the themes hosted their own
highlighting styles, but now that we are using the CDN, it is easier to
use a setting, which downstream themes can override.
In both built-in themes, the default next/prev shortcut keys were
changed from arrows to n/p as the arrows conflict with common browser
accessibility extensions.
In the mkdocs theme, users can now configure the shortcuts to whatever
they want. Note that these config options are theme specific. The
readthedocs theme does not get these options as they are not available
on the parent theme.
Fixes#1502
If the frontmatter is surrounded by YAML deliminators, then it is parsed
as YAML. Otherwise it is parsed as MultiMarkdown meta-data and each
value is returned as a joined string.
Closes#1471.
The sidebar was under the left margin of the main content and not
clickable. This moves the sidebar to the top so it is accessable. Not
sure when this got broken. Maybe #1387 or #1389 or #1395.
The built-in themes now include support for enabling/disabling
highlight.js. They also use a CDN to load the files. As the CDN only
includes 23 languages, a second setting to support more languages
is included.
If a user wishes to use a different tool for highlighting, they can
"disable" highlight.js and then use extra_css and/or extra_javasript
to add support for their tool of choice.
Currently all local URLs must be prepended with base_url while external
links must not. However, we can have both types of links in the same
collection. As prepreprocessing of extra_css and extra_javascript
settings is deprecated, we need a way to indicate the URL should be
prepended, but only if it needs to be. The same applies to external
links included in the site navigation.
Therefore, a new temaplte filter is provided which any URL can be passed
to. If the URL is absolute, it is returned unaltered. If it is relative
and the template context includes a `page` object, then a URL is
returned reltive to the page object. Otherwise, the URL is returned with
base_url prepended. This also results in cleaner output as paths are
normailized (redundant . are removed). Of course, the base_url tempalte
variable remains (it is not being deprecated -- in fact the new filter
relies on its existance) and template authors may continue to use it if
they desire.
The serve command overrights the the site_dir and can cause a crash when
clean_directory tries to remove files with Unicode chars in their
filenames if the paths are byte strings. As os.path.join and friends
will return a byte string (in PY2) if any part is passed in is a byte
string, we must ensure all parts are Unicode strings. By passing a
Unicode string to prefix, tempfile.mkdtemp returns a Unicode string
rather than the default byte string in PY2. And by passing the tempdir
path to load_config, it gets validated. Fixes#1516.
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.
If/when deploying to usr/org pages, the deploy script is run from the
Pages repo, not the project repo. Therefore, we need ot get the current
sha from the project repo.
