* Create real (no-op) methods for each event in the base class.
* Refactor event dispatcher to not check for methods' existence, instead just call them.
* Move documentation from Markdown into docstrings of these methods.
* Activate the 'mkdocstrings' plugin.
* Use 'mkdocstrings' to insert documentation from those docstrings into the site.
The result is exactly equivalent, just different syntax -- one that doesn't look weird in vanilla Markdown parsers such as on GitHub.
The output HTML before/after is equivalent , other than adding `<p class="admonition-title">Block</p>` in two cases, which I hid with CSS.
This also contributes to fixing the currently-present markdownlint MD053 violations, as it can't scan inside admonitions.
Add 'markdown-callouts' to dependencies and bump Markdown dep.
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.
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.
`urlparse(config['site_url']).path` can be empty if `site_url` does not end
in a slash. This ensures at least a slash is returned. Config validation
will add the slash if it is missing. Fixes#1785.
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.
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.
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.
* 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.
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 adds the ability to validate nested properties, such as
those within 'extra' and provides a deprecated config option for those
that have been moved.
Config validation now handles all extension processing:
* Builtin extensions are defined and within the default scheme.
* User extensions are defined only as a list in the config. Note, this is
a backward incompatable change from the previous (short-lived) release.
* The users extensions are added to the list of builtins.
* Any duplicates are accounted for in validation.
* Extension options are supported by a child key/value pair on the ext name.
* All extension options are compiled into a format Markdown accepts
within the validation process and are saved to the internal `mdx_configs`
config setting.
* The `mdx_configs` setting is private and raises an error if set by the user.
* A whole suite of tests were added to test all aspects of ext validation.
All relevant build tests were updated to pass the config to
`build.convert_markdown` as the config now handles all extension data.
The relevant documentation was updated to reflect the changes. While I was
at it, I spellchecked the entire document and made a few additional formatting
changes.
This fixes#519 plus a lot more.
The current pages configuration looks like this:
pages:
- ['index.md', 'Home']
- ['writing-your-docs.md', 'User Guide', 'Writing your docs']
- ['styling-your-docs.md', 'User Guide', 'Styling your docs']
- ['configuration.md', 'User Guide', 'Configuration']
- ['about/license.md', 'About', 'License']
- ['about/release-notes.md', 'About', 'Release Notes']
- ['about/contributing.md', 'About', 'Contributing']
This has a number of flaws:
- It isn't clear how to add second levels of navigation for
newcomers. This is often queried and not easy to document.
- We are representing a tree structure as a set of flat items
that need to be merged. This creates some interesting edge
cases, for example:
- ['writing-your-docs.md', 'User Guide']
- ['styling-your-docs.md', 'User Guide', 'Styling your docs']
Is the first entry a page with the title User Guide? or a page
in the User Guide category with an automatic title.
- We are currently limited to two levels deep in the navigation.
Changing this with the current structure isn't trivial.
This change adds a new format which makes the above configuration
look like this:
pages:
- Home: index.md
- User Guide:
- user-guide/writing-your-docs.md
- user-guide/styling-your-docs.md
- user-guide/configuration.md
- About:
- License: about/license.md
- about/release-notes.md
- Contributing: about/contributing.md
With this structure, we can more easily see the documentation
tree and it is far more obvious what the navigation will look
like. It also removes the ambiguous edge cases and opens up the
possibility of adding further levels to the navigation more
easily.
This change restructures the pages configuration, but doesn't yet
allow users to add further levels in the navigation.
Fixes#6
This is similar to extra_css and extra_javascript except it picks up
HTML and XML files and runs them through jinja2 with the global context.
This adds for quite a bit of flexability and allows people to easily add
custom site maps, static and templates htlp.
Fixes#28Fixes#44
