Documentation enhancements (#188)

mondeja · Dec 20, 2023 · 2017267 · 2017267
1 parent 1aa2f9c
commit 2017267
Show file tree

Hide file tree

Showing 7 changed files with 118 additions and 102 deletions.
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
@@ -1,3 +1,3 @@
 config:
-  no-duplicate-header: false
+  no-duplicate-heading: false
   no-inline-html: false
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.3
+    rev: v4.0.0-alpha.7
     hooks:
       - id: prettier
         types_or:
@@ -16,7 +16,7 @@ repos:
         minimum_pre_commit_version: 2.9.0
         exclude: ^locale
   - repo: https://github.com/mondeja/project-config
-    rev: v0.9.2
+    rev: v0.9.3
     hooks:
       - id: project-config
   - repo: meta
@@ -33,7 +33,7 @@ repos:
       - id: end-of-file-fixer
         name: end-of-file-fixer
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.0.292
+    rev: v0.1.8
     hooks:
       - id: ruff
         args:
@@ -63,11 +63,11 @@ repos:
       - id: untranslated-messages
       - id: remove-metadata
   - repo: https://github.com/adrienverge/yamllint
-    rev: v1.32.0
+    rev: v1.33.0
     hooks:
       - id: yamllint
   - repo: https://github.com/DavidAnson/markdownlint-cli2
-    rev: v0.10.0
+    rev: v0.11.0
     hooks:
       - id: markdownlint-cli2
         name: markdownlint-readme
@@ -79,7 +79,7 @@ repos:
         name: editorconfig-checker
         alias: ec
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.6.0
+    rev: v1.7.1
     hooks:
       - id: mypy
         files: ^src

diff --git a/README.md b/README.md
@@ -61,9 +61,9 @@ plugins:
       end: <!--end-->
 ```
 
-- <a name="config_tags" href="#config_tags">#</a> **opening_tag** and
-  **closing_tag**: The default opening and closing tags. By default are
-  `{%` and `%}`.
+#### `opening_tag` and `closing_tag`
+
+Default opening and closing tags. When not specified they are `{%` and `%}`.
 
 ```yaml
 plugins:
@@ -72,9 +72,12 @@ plugins:
       closing_tag: "!}"
 ```
 
-- <a name="config_exclude" href="#config_exclude">#</a> **exclude**: Define
-  global exclusion wildcard patterns. Relative paths defined here will be
-  relative to the _docs/_ directory.
+<!-- mdpo-disable-next-line -->
+
+#### `exclude`
+
+Global exclusion wildcard patterns. Relative paths defined here will be
+relative to the [`docs_dir`] directory.
 
 ```yaml
 plugins:
@@ -84,9 +87,11 @@ plugins:
         - api/**
 ```
 
-- <a name="config_cache" href="#config_cache">#</a> **cache**: Define a
-  expiration time in seconds for cached HTTP requests when including
-  from URLs.
+<!-- mdpo-disable-next-line -->
+
+#### `cache`
+
+Expiration time in seconds for cached HTTP requests when including from URLs.
 
 ```yaml
 plugins:
@@ -113,8 +118,8 @@ Paths of included files can be either:
 - Local files:
   - Absolute paths (starting with a path separator).
   - Relative from the file that includes them (starting with `./` or `../`).
-  - Relative to the `docs_dir` directory. For instance if your `docs_dir` is
-    _./docs/_, then `includes/header.md` will match the file _./docs/includes/header.md_`.
+  - Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is
+    _./docs/_, then `includes/header.md` will match the file _./docs/includes/header.md_.
 - [Bash wildcard globs] matching multiple local files.
 
 File paths to include and string arguments can be wrapped by double `"` or
@@ -283,3 +288,4 @@ Includes the content of a file or a group of files.
 [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
 [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
 [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax
+[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
diff --git a/locale/es/README.md b/locale/es/README.md
@@ -50,8 +50,9 @@ plugins:
       end: <!--end-->
 ```
 
-- <a name="config_tags" href="#config_tags">#</a> **opening_tag** and
-**closing_tag**: Las etiquetas de apertura y cierre. Por defecto son `{%` y
+#### `opening_tag` y `closing_tag`
+
+Etiquetas de apertura y cierre por defecto. Cuando no se especifican son `{%` y
 `%}`.
 
 ```yaml
@@ -61,9 +62,10 @@ plugins:
       closing_tag: "!}"
 ```
 
-- <a name="config_exclude" href="#config_exclude">#</a> **exclude**: Define
-patrones de comodín de exclusión globales. Las rutas relativas definidas aquí
-serán relativas al directorio *docs/*.
+#### `exclude`
+
+Patrones de comodín de exclusión globales. Las rutas relativas definidas aquí
+serán relativas al directorio [`docs_dir`].
 
 ```yaml
 plugins:
@@ -73,8 +75,9 @@ plugins:
         - api/**
 ```
 
-- <a name="config_cache" href="#config_cache">#</a> **cache**: Define un tiempo
-de caducidad en segundos para las solicitudes HTTP almacenadas en caché al
+#### `cache`
+
+Tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en caché al
 incluir desde URL.
 
 ```yaml
@@ -102,8 +105,8 @@ Las rutas de los archivos a incluir pueden ser:
 - Archivos locales:
    - Rutas absolutas (comenzando con un separador de rutas).
    - Relativas desde el archivo que las incluye (empezando por `./` o `../`).
-   - Relativo al directorio `docs_dir`. Por ejemplo, si tu `docs_dir` es _./docs/_,
-entonces `includes/header.md` coincidirá con el archivo
+   - Relativo al directorio [`docs_dir`]. Por ejemplo, si tu `docs_dir` es
+_./docs/_, entonces `includes/header.md` coincidirá con el archivo
 *_./docs/includes/header.md_*.
 - [Bash wildcard globs] matching multiple local files.
 [Patrones glob de Bash]
@@ -279,3 +282,4 @@ separar este plugin de la documentación de
 [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
 [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
 [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax
+[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
diff --git a/locale/es/README.md.po b/locale/es/README.md.po
@@ -27,9 +27,6 @@ msgstr ""
 "Incluye contenido de archivos Markdown, opcionalmente usando dos "
 "delimitadores para filtrar el contenido a incluir."
 
-msgid "Examples"
-msgstr "Ejemplos"
-
 msgid "Acknowledgment"
 msgstr "Agradecimiento"
 
@@ -285,15 +282,6 @@ msgstr ""
 "El comportamiento global del plugin puede ser personalizado en la "
 "configuración."
 
-msgid ""
-"<a name=\"config_tags\" href=\"#config_tags\">#</a> **opening_tag** and "
-"**closing_tag**: The default opening and closing tags. By default are `{%` "
-"and `%}`."
-msgstr ""
-"<a name=\"config_tags\" href=\"#config_tags\">#</a> **opening_tag** and "
-"**closing_tag**: Las etiquetas de apertura y cierre. Por defecto son `{%` y "
-"`%}`."
-
 msgid "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 msgstr "[pypi-link]: https://pypi.org/project/mkdocs-include-markdown-plugin"
 
@@ -367,24 +355,6 @@ msgid ""
 msgstr ""
 "[Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax"
 
-msgid ""
-"<a name=\"config_exclude\" href=\"#config_exclude\">#</a> **exclude**: "
-"Define global exclusion wildcard patterns. Relative paths defined here will "
-"be relative to the *docs/* directory."
-msgstr ""
-"<a name=\"config_exclude\" href=\"#config_exclude\">#</a> **exclude**: "
-"Define patrones de comodín de exclusión globales. Las rutas relativas "
-"definidas aquí serán relativas al directorio *docs/*."
-
-msgid ""
-"<a name=\"config_cache\" href=\"#config_cache\">#</a> **cache**: Define a "
-"expiration time in seconds for cached HTTP requests when including from "
-"URLs."
-msgstr ""
-"<a name=\"config_cache\" href=\"#config_cache\">#</a> **cache**: Define un "
-"tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en "
-"caché al incluir desde URL."
-
 msgid ""
 "Relative from the file that includes them (starting with `./` or `../`)."
 msgstr ""
@@ -399,11 +369,42 @@ msgstr ""
 "instalada. Puedes incluirla en la instalación del plugin añadiendo el extra "
 "`cache`:"
 
+msgid "`opening_tag` and `closing_tag`"
+msgstr "`opening_tag` y `closing_tag`"
+
+msgid ""
+"Default opening and closing tags. When not specified they are `{%` and `%}`."
+msgstr ""
+"Etiquetas de apertura y cierre por defecto. Cuando no se especifican son "
+"`{%` y `%}`."
+
+msgid ""
+"Global exclusion wildcard patterns. Relative paths defined here will be "
+"relative to the [`docs_dir`] directory."
+msgstr ""
+"Patrones de comodín de exclusión globales. Las rutas relativas definidas "
+"aquí serán relativas al directorio [`docs_dir`]."
+
+msgid ""
+"Expiration time in seconds for cached HTTP requests when including from "
+"URLs."
+msgstr ""
+"Tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en "
+"caché al incluir desde URL."
+
+msgid ""
+"[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir"
+msgstr ""
+"[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir"
+
+msgid "Examples"
+msgstr "Ejemplos"
+
 msgid ""
-"Relative to the `docs_dir` directory. For instance if your `docs_dir` is "
+"Relative to the [`docs_dir`] directory. For instance if your `docs_dir` is "
 "*./docs/*, then `includes/header.md` will match the file "
-"*./docs/includes/header.md*`."
+"*./docs/includes/header.md*."
 msgstr ""
-"Relativo al directorio `docs_dir`. Por ejemplo, si tu `docs_dir` es "
+"Relativo al directorio [`docs_dir`]. Por ejemplo, si tu `docs_dir` es "
 "_./docs/_, entonces `includes/header.md` coincidirá con el archivo "
 "*_./docs/includes/header.md_*."
diff --git a/locale/fr/README.md b/locale/fr/README.md
@@ -49,9 +49,10 @@ plugins:
       end: <!--end-->
 ```
 
-- <a name="config_tags" href="#config_tags">#</a> **opening_tag** and
-**closing_tag**: Les balises d'ouverture et de fermeture par défaut. Par
-défaut sont `{%` et `%}`.
+#### `opening_tag` et `closing_tag`
+
+Balises d'ouverture et de fermeture par défaut. Lorsqu'elles ne sont pas
+spécifiées, elles sont `{%` et `%}`.
 
 ```yaml
 plugins:
@@ -60,9 +61,10 @@ plugins:
       closing_tag: "!}"
 ```
 
-- <a name="config_exclude" href="#config_exclude">#</a> **exclude**: Définissez
-des modèles génériques d'exclusion globale. Les chemins de fichiers relatifs
-définis ici seront relatifs au répertoire *docs/*.
+#### `exclude`
+
+Modèles de globes d'exclusion globaux. Les chemins relatifs définis ici seront
+relatifs au répertoire [`docs_dir`].
 
 ```yaml
 plugins:
@@ -72,8 +74,9 @@ plugins:
         - api/**
 ```
 
-- <a name="config_cache" href="#config_cache">#</a> **cache**: Définissez un
-délai d'expiration en secondes pour les requêtes HTTP mises en cache lors de
+#### `cache`
+
+Délai d'expiration en secondes pour les requêtes HTTP mises en cache lors de
 l'inclusion d'URL.
 
 ```yaml
@@ -102,7 +105,7 @@ Les chemins des fichiers inclus peuvent être soit:
 - Fichiers locaux:
    - Chemins de fichier absolus (commençant par un séparateur de chemin).
    - Relatifs du fichiers qui les inclut (commençant par `./` ou `../`).
-   - Relatif au répertoire `docs_dir`. Par exemple, si votre `docs_dir` est
+   - Relatif au répertoire [`docs_dir`]. Par exemple, si votre `docs_dir` est
 _./docs/_, alors `includes/header.md` va correspondre au fichier
 *_./docs/includes/header.md_*.
 - Globs génériques Bash correspondant à plusieurs fichiers locaux.
@@ -276,3 +279,4 @@ autorisations][cibuildwheel-470] pour séparer ce plugin de la documentation de
 [es-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/es/README.md
 [fr-readme-link]: https://github.com/mondeja/mkdocs-include-markdown-plugin/blob/master/locale/fr/README.md
 [Bash wildcard globs]: https://facelessuser.github.io/wcmatch/glob/#syntax
+[`docs_dir`]: https://www.mkdocs.org/user-guide/configuration/#docs_dir