Documentation

docs/plugins/privacy.md

@@ -471,6 +471,8 @@ plugins:
 
 ## Limitations
 
+### Dynamic URLs
+
 Dynamically created URLs as part of scripts are not detected, and thus cannot be
 downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
 
@@ -485,15 +487,18 @@ Instead, always use fully qualified URLs:
 const url ="https://example.com/script.js"
 ```
 
-Note that the plugin does not scan embedded HTML for external assets –
+### Embedded HTML
-this is related to MkDocs, as it does not process HTML
-(not to be confused with the generated HTML) in the plugin pipeline.
-To self-host external assets of an embedded HTML,
-it has to be explicitly listed under [`extra_templates`][extra_templates] in `mkdocs.yml`:
 
-  [extra_templates]: https://www.mkdocs.org/user-guide/configuration/#extra_templates
+By default, embedded HTML files (e.g. in iframes) are not scanned for external
+assets. This is a limitation of MkDocs, as it considers `.html` files to be
+templates, which must be explicitly listed under
+[`extra_templates`][mkdocs.extra_templates]. Thus, to self-host external assets
+of an embedded HTML file:
 
 ``` yaml
 extra_templates:
-  - embed.html
+  - iframe.html
 ```
+
+Note that the path to `iframe.html` is relative to the
+[`docs_dir`][mkdocs.docs_dir] directory.

docs/setup/setting-up-a-blog.md

@@ -72,7 +72,6 @@ We'll add more settings here, as we discover new use cases.
   [Insiders]: ../insiders/index.md
   [built-in blog plugin]: ../plugins/blog.md
   [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-  [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
   [start writing your first post]: #writing-your-first-post
 
   [config.archive_pagination]: ../plugins/blog.md#config.archive_pagination
@@ -469,7 +468,7 @@ links:
 ...
 ```
 
-You can use the exact same syntax as for the [`nav`][nav] section in
+You can use the exact same syntax as for the [`nav`][mkdocs.nav] section in
 `mkdocs.yml`, which means you can set explicit titles for links, add external
 links and even use nesting:
 
@@ -489,14 +488,13 @@ links:
 ```
 
 If you look closely, you'll realize that you can even use an anchor to link to
-a specific section of a document, extending the possibilities of the [`nav`][nav]
+a specific section of a document, extending the possibilities of the
-syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets
+[`nav`][mkdocs.nav] syntax in `mkdocs.yml`. The [built-in blog plugin] resolves
-the title of the anchor as a [subtitle] of the related link.
+the anchor and sets the title of the anchor as a [subtitle] of the related link.
 
-Note that all links must be relative to [`docs_dir`][docs_dir], as is also the
+Note that all links must be relative to [`docs_dir`][mkdocs.docs_dir], as is
-case for the [`nav`][nav] setting.
+also the case for the [`nav`][mkdocs.nav] setting.
 
-  [nav]: https://www.mkdocs.org/user-guide/configuration/#nav
   [subtitle]: ../reference/index.md#setting-the-page-subtitle
 
 #### Linking from and to posts
@@ -624,9 +622,9 @@ values defined for a post, which means you can define common properties in
 ### Adding pages
 
 Besides posts, it's also possible to add static pages to your blog by listing
-the pages in the [`nav`][nav] section of `mkdocs.yml`. All generated indexes
+the pages in the [`nav`][mkdocs.nav] section of `mkdocs.yml`. All generated
-are included after the last specified page. For example, to add a page on the
+indexes are included after the last specified page. For example, to add a page
-authors of the blog, add the following to `mkdocs.yml`:
+on the authors of the blog, add the following to `mkdocs.yml`:
 
 ``` yaml
 nav:

includes/mkdocs.md

@@ -3,6 +3,7 @@
   [mkdocs.metadata]: https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data
   [mkdocs.env]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
   [mkdocs.docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+  [mkdocs.extra_templates]: https://www.mkdocs.org/user-guide/configuration/#extra_templates
   [mkdocs.site_dir]: https://www.mkdocs.org/user-guide/configuration/#site_dir
   [mkdocs.site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
   [mkdocs.site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description