From cf2b39d1c2858c53c17e4b5ce8ee33a5c94b6d98 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 9 Oct 2024 10:09:44 +0200 Subject: [PATCH] Documentation --- docs/plugins/privacy.md | 19 ++++++++++++------- docs/setup/setting-up-a-blog.md | 20 +++++++++----------- includes/mkdocs.md | 1 + 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/plugins/privacy.md b/docs/plugins/privacy.md index cdde6591f..47052a132 100644 --- a/docs/plugins/privacy.md +++ b/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 – -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`: +### Embedded HTML - [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. diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md index 31ad90dbc..ed44ee281 100644 --- a/docs/setup/setting-up-a-blog.md +++ b/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] -syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets -the title of the anchor as a [subtitle] of the related link. +a specific section of a document, extending the possibilities of the +[`nav`][mkdocs.nav] syntax in `mkdocs.yml`. The [built-in blog plugin] resolves +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 -case for the [`nav`][nav] setting. +Note that all links must be relative to [`docs_dir`][mkdocs.docs_dir], as is +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 -are included after the last specified page. For example, to add a page on the -authors of the blog, add the following to `mkdocs.yml`: +the pages in the [`nav`][mkdocs.nav] section of `mkdocs.yml`. All generated +indexes are included after the last specified page. For example, to add a page +on the authors of the blog, add the following to `mkdocs.yml`: ``` yaml nav: diff --git a/includes/mkdocs.md b/includes/mkdocs.md index fd8eb483a..67f7491c0 100644 --- a/includes/mkdocs.md +++ b/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