Add documentation for HTTP cache feature

README.md

@@ -51,7 +51,7 @@ The global behaviour of the plugin can be customized in the configuration.
   **closing_tag**: The default opening and closing tags. By default are
   `{%` and `%}`.
 
-The rest of the options will define the default values passed to arguments
+Most of the settings will define the default values passed to arguments
 of directives and are documented in the [reference](#reference).
 
 ```yaml
@@ -61,19 +61,39 @@ plugins:
       closing_tag: "!}"
       encoding: ascii
       preserve_includer_indent: false
-      dedent: true
-      trailing_newlines: false
-      comments: false
+      dedent: false
+      trailing_newlines: true
+      comments: true
+```
+
+The `cache` setting defines a expiration time in seconds for HTTP requests
+when including from URLs.
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+```
+
+In order to use this feature, the dependency [platformdirs] must be installed.
+You can include it in the installation of the plugin adding the `cache` extra:
+
+```txt
+# requirements.txt
+mkdocs-include-markdown-plugin[cache]
 ```
 
 ### Reference
 
 This plugin provides two directives, one to include Markdown files and another
 to include files of any type.
 
-Paths of included files can be absolute or relative to the path of the file
-that includes them. This argument also accept globs, in which case certain
-paths can be ignored using the `exclude` argument.
+Paths of included files can be either:
+
+- Local files with absolute or relative paths to the file that includes them.
+- Globs matching multiples files, in which case certain paths can be ignored
+  using the `exclude` argument.
+- URLs to include remote content.
 
 File paths to include and string arguments can be wrapped by double `"` or
 single `'` quotes, which can be escaped prepending them a `\` character as
@@ -228,6 +248,7 @@ Includes the content of a file or a group of files.
 [coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin
 [license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
+[platformdirs]: https://pypi.org/project/platformdirs/
 [cibuildwheel-470]: https://github.com/joerick/cibuildwheel/issues/470
 [cibuildwheel-repo-link]: https://github.com/joerick/cibuildwheel
 [mkdocs-macros-plugin-link]: https://mkdocs-macros-plugin.readthedocs.io

locale/es/README.md

@@ -39,8 +39,9 @@ El comportamiento global del plugin puede ser personalizado en la configuración
 **closing_tag**: Las etiquetas de apertura y cierre. Por defecto son `{%` y
 `%}`.
 
-El resto de las opciones definirán los valores por defecto pasados a los
-argumentos de las directivas y están documentados en la [referencia](#reference).
+La mayoría de los parámetros de configuración definirán los valores por defecto
+pasados a los argumentos de las directivas y están documentados en la
+[referencia](#referencia).
 
 ```yaml
 plugins:
@@ -49,19 +50,39 @@ plugins:
       closing_tag: "!}"
       encoding: ascii
       preserve_includer_indent: false
-      dedent: true
-      trailing_newlines: false
-      comments: false
+      dedent: false
+      trailing_newlines: true
+      comments: true
+```
+
+La configuración `cache` define un tiempo de expiración en segundos para las
+peticiones HTTP cuando se incluye desde URLs.
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+```
+
+Para usar esta funcionalidad, la dependencia [platformdirs] debe ser instalada.
+Puedes incluirla en la instalación del plugin añadiendo el extra `cache`:
+
+```txt
+# requirements.txt
+mkdocs-include-markdown-plugin[cache]
 ```
 
 ### Referencia
 
 Este plugin provee dos directivas, una para incluir archivos Markdown y otra para
 incluir archivos de cualquier tipo.
 
-Las rutas de los archivos incluidos pueden ser absolutas o relativas a la ruta
-del archivo que las incluye. Este argumento también acepta globs, en cuyo caso
-ciertas rutas pueden ser ignoradas usando el argumento `exclude`.
+Las rutas de los archivos a incluir pueden ser:
+
+- Archivos locales con rutas absolutas o relativas al archivo que los incluye.
+- Globs coincidiendo con múltiples archivos, en cuyo caso ciertas rutas pueden
+ser ignoradas usando el argumento `exclude`.
+- URLs para incluir contenido remoto.
 
 Las rutas de archivo para incluir y los argumentos de cadena se pueden envolver
 con comillas dobles `"` o simples `'`, que se pueden escapar anteponiendo un
@@ -220,6 +241,7 @@ separar este plugin de la documentación de
 [coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin
 [license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
+[platformdirs]: https://pypi.org/project/platformdirs/
 [cibuildwheel-470]: https://github.com/joerick/cibuildwheel/issues/470
 [cibuildwheel-repo-link]: https://github.com/joerick/cibuildwheel
 [mkdocs-macros-plugin-link]: https://mkdocs-macros-plugin.readthedocs.io

locale/es/README.md.po

@@ -255,15 +255,6 @@ msgstr ""
 "deshabilitada, los saltos de línea finales que se encuentran en el contenido"
 " a incluir se eliminan. Los valores posibles son `true` y `false`."
 
-msgid ""
-"Paths of included files can be absolute or relative to the path of the file "
-"that includes them. This argument also accept globs, in which case certain "
-"paths can be ignored using the `exclude` argument."
-msgstr ""
-"Las rutas de los archivos incluidos pueden ser absolutas o relativas a la "
-"ruta del archivo que las incluye. Este argumento también acepta globs, en "
-"cuyo caso ciertas rutas pueden ser ignoradas usando el argumento `exclude`."
-
 msgid ""
 "The arguments **start** and **end** may contain usual (Python-style) escape "
 "sequences like `\\n` to match against newlines."
@@ -317,14 +308,6 @@ msgstr ""
 "**closing_tag**: Las etiquetas de apertura y cierre. Por defecto son `{%` y "
 "`%}`."
 
-msgid ""
-"The rest of the options will define the default values passed to arguments "
-"of directives and are documented in the [reference](#reference)."
-msgstr ""
-"El resto de las opciones definirán los valores por defecto pasados a los "
-"argumentos de las directivas y están documentados en la "
-"[referencia](#reference)."
-
 msgid "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 msgstr "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 
@@ -364,3 +347,48 @@ msgid ""
 msgstr ""
 "[license-link]: https://github.com/mondeja/mkdocs-include-markdown-"
 "plugin/blob/master/LICENSE"
+
+msgid "[platformdirs]: https://pypi.org/project/platformdirs/"
+msgstr "[platformdirs]: https://pypi.org/project/platformdirs/"
+
+msgid ""
+"Most of the settings will define the default values passed to arguments of "
+"directives and are documented in the [reference](#reference)."
+msgstr ""
+"La mayoría de los parámetros de configuración definirán los valores por "
+"defecto pasados a los argumentos de las directivas y están documentados en "
+"la [referencia](#referencia)."
+
+msgid ""
+"The `cache` setting defines a expiration time in seconds for HTTP requests "
+"when including from URLs."
+msgstr ""
+"La configuración `cache` define un tiempo de expiración en segundos para las"
+" peticiones HTTP cuando se incluye desde URLs."
+
+msgid "Paths of included files can be either:"
+msgstr "Las rutas de los archivos a incluir pueden ser:"
+
+msgid ""
+"Globs matching multiples files, in which case certain paths can be ignored "
+"using the `exclude` argument."
+msgstr ""
+"Globs coincidiendo con múltiples archivos, en cuyo caso ciertas rutas pueden"
+" ser ignoradas usando el argumento `exclude`."
+
+msgid "URLs to include remote content."
+msgstr "URLs para incluir contenido remoto."
+
+msgid ""
+"In order to use this feature, the dependency [platformdirs] must be "
+"installed. You can include it in the installation of the plugin adding the "
+"`cache` extra:"
+msgstr ""
+"Para usar esta funcionalidad, la dependencia [platformdirs] debe ser "
+"instalada. Puedes incluirla en la instalación del plugin añadiendo el extra "
+"`cache`:"
+
+msgid ""
+"Local files with absolute or relative paths to the file that includes them."
+msgstr ""
+"Archivos locales con rutas absolutas o relativas al archivo que los incluye."

locale/fr/README.md

@@ -40,8 +40,8 @@ Le comportement global du plugin peut être personnalisé dans la configuration.
 **closing_tag**: Les balises d'ouverture et de fermeture par défaut. Par
 défaut sont `{%` et `%}`.
 
-Le reste des options définira les valeurs par défaut passées aux arguments des
-directives et sont documentées dans la [référence](#reference).
+La plupart des paramètres définissent les valeurs par défaut transmises aux
+arguments des directives et sont documentés dans la [référence](#référence).
 
 ```yaml
 plugins:
@@ -50,19 +50,41 @@ plugins:
       closing_tag: "!}"
       encoding: ascii
       preserve_includer_indent: false
-      dedent: true
-      trailing_newlines: false
-      comments: false
+      dedent: false
+      trailing_newlines: true
+      comments: true
+```
+
+Le paramètre `cache` définit un délai d'expiration en secondes pour les requêtes
+HTTP lors de l'inclusion d'URL.
+
+```yaml
+plugins:
+  - include-markdown:
+      cache: 600
+```
+
+Pour utiliser cette fonctionnalité, la dépendance [platformdirs] doit être
+installée. Vous pouvez l'inclure dans l'installation du plugin en ajoutant le
+supplément `cache`:
+
+```txt
+# requirements.txt
+mkdocs-include-markdown-plugin[cache]
 ```
 
 ### Référence
 
 Ce plugin fournit deux directives, une pour inclure des fichiers Markdown et une
 autre pour inclure des fichiers de tout type.
 
-Les paths des fichiers inclus peuvent être absolus ou relatifs au le path du
-fichier qui les inclut. Cet argument accepte également des globs, auquel cas
-certains paths peuvent être ignorés à l'aide de l'argument `exclude`.
+Les chemins des fichiers inclus peuvent être soit:
+
+- Fichiers locaux avec des chemins absolus ou relatifs vers le fichier qui les
+contient.
+- Globs correspondant à plusieurs fichiers, auquel cas certains chemins peuvent
+être ignorés en utilisant l'argument `exclude`.
+- URL pour inclure du contenu distant.
 
 Les chemins d'accès aux fichiers à inclure et les arguments de chaîne peuvent
 être entourés de guillemets doubles `"` ou simples `'`, qui peuvent être
@@ -220,6 +242,7 @@ autorisations][cibuildwheel-470] pour séparer ce plugin de la documentation de
 [coverage-link]: https://app.codecov.io/gh/mondeja/mkdocs-include-markdown-plugin
 [license-image]: https://img.shields.io/pypi/l/mkdocs-include-markdown-plugin?color=light-green&logo=apache&logoColor=white
 [license-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/LICENSE
+[platformdirs]: https://pypi.org/project/platformdirs/
 [cibuildwheel-470]: https://github.com/joerick/cibuildwheel/issues/470
 [cibuildwheel-repo-link]: https://github.com/joerick/cibuildwheel
 [mkdocs-macros-plugin-link]: https://mkdocs-macros-plugin.readthedocs.io

locale/fr/README.md.po

@@ -255,15 +255,6 @@ msgstr ""
 "désactivée, les nouvelles lignes de fin trouvées dans le contenu à inclure "
 "sont supprimées. Les valeurs possibles sont `true` et `false`."
 
-msgid ""
-"Paths of included files can be absolute or relative to the path of the file "
-"that includes them. This argument also accept globs, in which case certain "
-"paths can be ignored using the `exclude` argument."
-msgstr ""
-"Les paths des fichiers inclus peuvent être absolus ou relatifs au le path du"
-" fichier qui les inclut. Cet argument accepte également des globs, auquel "
-"cas certains paths peuvent être ignorés à l'aide de l'argument `exclude`."
-
 msgid ""
 "The arguments **start** and **end** may contain usual (Python-style) escape "
 "sequences like `\\n` to match against newlines."
@@ -317,13 +308,6 @@ msgstr ""
 "Le comportement global du plugin peut être personnalisé dans la "
 "configuration."
 
-msgid ""
-"The rest of the options will define the default values passed to arguments "
-"of directives and are documented in the [reference](#reference)."
-msgstr ""
-"Le reste des options définira les valeurs par défaut passées aux arguments "
-"des directives et sont documentées dans la [référence](#reference)."
-
 msgid "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 msgstr "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 
@@ -363,3 +347,48 @@ msgid ""
 msgstr ""
 "[license-link]: https://github.com/mondeja/mkdocs-include-markdown-"
 "plugin/blob/master/LICENSE"
+
+msgid "[platformdirs]: https://pypi.org/project/platformdirs/"
+msgstr "[platformdirs]: https://pypi.org/project/platformdirs/"
+
+msgid ""
+"Most of the settings will define the default values passed to arguments of "
+"directives and are documented in the [reference](#reference)."
+msgstr ""
+"La plupart des paramètres définissent les valeurs par défaut transmises aux "
+"arguments des directives et sont documentés dans la [référence](#référence)."
+
+msgid ""
+"The `cache` setting defines a expiration time in seconds for HTTP requests "
+"when including from URLs."
+msgstr ""
+"Le paramètre `cache` définit un délai d'expiration en secondes pour les "
+"requêtes HTTP lors de l'inclusion d'URL."
+
+msgid "Paths of included files can be either:"
+msgstr "Les chemins des fichiers inclus peuvent être soit:"
+
+msgid ""
+"Globs matching multiples files, in which case certain paths can be ignored "
+"using the `exclude` argument."
+msgstr ""
+"Globs correspondant à plusieurs fichiers, auquel cas certains chemins "
+"peuvent être ignorés en utilisant l'argument `exclude`."
+
+msgid "URLs to include remote content."
+msgstr "URL pour inclure du contenu distant."
+
+msgid ""
+"In order to use this feature, the dependency [platformdirs] must be "
+"installed. You can include it in the installation of the plugin adding the "
+"`cache` extra:"
+msgstr ""
+"Pour utiliser cette fonctionnalité, la dépendance [platformdirs] doit être "
+"installée. Vous pouvez l'inclure dans l'installation du plugin en ajoutant "
+"le supplément `cache`:"
+
+msgid ""
+"Local files with absolute or relative paths to the file that includes them."
+msgstr ""
+"Fichiers locaux avec des chemins absolus ou relatifs vers le fichier qui les"
+" contient."