Deduplicate common arguments in documentation

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: v3.6.2
+    rev: v3.7.4
     hooks:
       - id: prettier
         types_or:
@@ -37,14 +37,14 @@ repos:
       - id: end-of-file-fixer
         name: end-of-file-fixer
   - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.33.3
+    rev: 0.36.0
     hooks:
       - id: check-github-workflows
         name: check-github-workflows
         args:
           - --verbose
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.10
+    rev: v0.14.10
     hooks:
       - id: ruff
         args:
@@ -78,19 +78,19 @@ repos:
     hooks:
       - id: yamllint
   - repo: https://github.com/DavidAnson/markdownlint-cli2
-    rev: v0.18.1
+    rev: v0.20.0
     hooks:
       - id: markdownlint-cli2
         name: markdownlint-readme
         files: ^README.md
   - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
-    rev: 3.4.0
+    rev: 3.6.0
     hooks:
       - id: editorconfig-checker
         name: editorconfig-checker
         alias: ec
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.17.1
+    rev: v1.19.1
     hooks:
       - id: mypy
         name: mypy-mkdocs-1.5.0
@@ -100,7 +100,7 @@ repos:
           - platformdirs
           - wcmatch
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.17.1
+    rev: v1.19.1
     hooks:
       - id: mypy
         name: mypy-mkdocs-1.6.0

README.md

@@ -146,6 +146,8 @@ plugins:
 This plugin provides two directives, one to include Markdown files and another
 to include files of any type.
 
+#### Common arguments
+
 Paths of included files can be either:
 
 - URLs to include remote content.
@@ -164,34 +166,27 @@ single `'` quotes, which can be escaped prepending them a `\` character as
 The arguments **start** and **end** may contain usual (Python-style) escape
 sequences like `\n` to match against newlines.
 
-<!-- mdpo-disable-next-line -->
-
-#### **`include-markdown`**
-
-Includes Markdown files content, optionally using two delimiters to filter the
-content to include.
-
-- <a name="include-markdown_start" href="#include-markdown_start">#</a>
+- <a name="include_start" href="#include_start">#</a>
   **start**: Delimiter that marks the beginning of the content to include.
-- <a name="include-markdown_end" href="#include-markdown_end">#</a>
+- <a name="include_end" href="#include_end">#</a>
   **end**: Delimiter that marks the end of the content to include.
-- <a name="include-markdown_preserve-includer-indent" href="#include-markdown_preserve-includer-indent">#</a>
+- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
   **preserve-includer-indent** (_true_): When this option is enabled (default),
   every line of the content to include is indented with the same number of
   spaces used to indent the includer `{% %}` template. Possible values are
   `true` and `false`.
-- <a name="include-markdown_dedent" href="#include-markdown_dedent">#</a>
+- <a name="include_dedent" href="#include_dedent">#</a>
   **dedent** (_false_): If enabled, the included content will be dedented.
-- <a name="include-markdown_exclude" href="#include-markdown_exclude">#</a>
+- <a name="include_exclude" href="#include_exclude">#</a>
   **exclude**: Specify with a glob which files should be ignored. Only useful
   when passing globs to include multiple files.
-- <a name="include-markdown_trailing-newlines" href="#include-markdown_trailing-newlines">#</a>
+- <a name="include_trailing-newlines" href="#include_trailing-newlines">#</a>
   **trailing-newlines** (_true_): When this option is disabled, the trailing newlines
   found in the content to include are stripped. Possible values are `true` and `false`.
-- <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
+- <a name="include_recursive" href="#include_recursive">#</a>
   **recursive** (_true_): When this option is disabled, included files are not
   processed for recursive includes. Possible values are `true` and `false`.
-- <a name="include-markdown_order" href="#include-markdown_order">#</a>
+- <a name="include_order" href="#include_order">#</a>
   **order** (_'alpha-path'_): Define the order in which multiple files are included
   when using globs. Possible values are:
   - A combination of an optional order type and an optional order by separated
@@ -206,8 +201,8 @@ content to include.
       - `'path'` (default): Order by full file path.
       - `'name'`: Order by file name only.
       - `'extension'`: Order by file extension.
-  - A combination of an optional prefix hyphen to denote ascending order and
-    one of the following values in the form `[-]<value>` where `<value>` is one of:
+  - A combination of an optional prefix hyphen to denote ascending order and one
+    of the following values in the form `[-]<value>` where `<value>` is one of:
     - `'size'`: Order by file size.
     - `'mtime'`: Order by file modification time.
     - `'ctime'`: Order by file creation time (or the last metadata change time
@@ -217,9 +212,17 @@ content to include.
   - `'system'`: Order provided by the operating system. This is the same as not
     specifying any order and relying on the default order of the filesystem. This
     may be different between operating systems, so use it with care.
-- <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
+- <a name="include_encoding" href="#include_encoding">#</a>
   **encoding** (_'utf-8'_): Specify the encoding of the included file.
   If not defined `'utf-8'` will be used.
+
+<!-- mdpo-disable-next-line -->
+
+#### **`include-markdown`**
+
+Includes Markdown files content, optionally using two delimiters to filter the
+content to include.
+
 - <a name="include-markdown_rewrite-relative-urls" href="#include-markdown_rewrite-relative-urls">#</a>
   **rewrite-relative-urls** (_true_): When this option is enabled (default),
   Markdown links and images in the content that are specified by a relative URL
@@ -296,56 +299,6 @@ content to include.
 
 Includes the content of a file or a group of files.
 
-- <a name="include_start" href="#include_start">#</a>
-  **start**: Delimiter that marks the beginning of the content to include.
-- <a name="include_end" href="#include_end">#</a>
-  **end**: Delimiter that marks the end of the content to include.
-- <a name="include_preserve-includer-indent" href="#include_preserve-includer-indent">#</a>
-  **preserve-includer-indent** (_true_): When this option is enabled (default),
-  every line of the content to include is indented with the same number of
-  spaces used to indent the includer `{% %}` template. Possible values are
-  `true` and `false`.
-- <a name="include_dedent" href="#include_dedent">#</a>
-  **dedent** (_false_): If enabled, the included content will be dedented.
-- <a name="include_exclude" href="#include_exclude">#</a>
-  **exclude**: Specify with a glob which files should be ignored. Only useful
-  when passing globs to include multiple files.
-- <a name="include_trailing-newlines" href="#include_trailing-newlines">#</a>
-  **trailing-newlines** (_true_): When this option is disabled, the trailing newlines
-  found in the content to include are stripped. Possible values are `true` and `false`.
-- <a name="include_recursive" href="#include_recursive">#</a>
-  **recursive** (_true_): When this option is disabled, included files are not
-  processed for recursive includes. Possible values are `true` and `false`.
-- <a name="include_order" href="#include_order">#</a>
-  **order** (_'alpha-path'_): Define the order in which multiple files are included
-  when using globs. Possible values are:
-  - A combination of an optional order type and an optional order by separated
-    by a hyphen (`-`), and optionally prefixed by a hyphen (`-`) to indicate
-    ascending order. If an order type or an order by is not specified, the defaults
-    are used. It follows the form:
-    `[-]<order_type>-<order_by>` where:
-    - **Order type**:
-      - `'alpha'` (default): Alphabetical order.
-      - `'natural'`: Natural order, so that e.g. `file2.md` comes before `file10.md`.
-    - **Order by**:
-      - `'path'` (default): Order by full file path.
-      - `'name'`: Order by file name only.
-      - `'extension'`: Order by file extension.
-  - A combination of an optional prefix hyphen to denote ascending order and
-    one of the following values in the form `[-]<value>` where `<value>` is one of:
-    - `'size'`: Order by file size.
-    - `'mtime'`: Order by file modification time.
-    - `'ctime'`: Order by file creation time (or the last metadata change time
-      on Unix systems).
-    - `'atime'`: Order by file last access time.
-  - `'random'`: Random order.
-  - `'system'`: Order provided by the operating system. This is the same as not
-    specifying any order and relying on the default order of the filesystem. This
-    may be different between operating systems, so use it with care.
-- <a name="include_encoding" href="#include_encoding">#</a>
-  **encoding** (_'utf-8'_): Specify the encoding of the included file.
-  If not defined `'utf-8'` will be used.
-
 ##### Examples
 
 ```jinja

locale/es/README.md

@@ -129,6 +129,8 @@ plugins:
 Este plugin provee dos directivas, una para incluir archivos Markdown y otra para
 incluir archivos de cualquier tipo.
 
+#### Argumentos comunes
+
 Las rutas de los archivos a incluir pueden ser:
 
 - URLs para incluir contenido remoto.
@@ -148,38 +150,32 @@ Las cadenas **start** y **end** pueden contener caracteres usuales de secuencias
 de escape (al estilo Python) como `\n` para hacer coincidir contra caracteres de
 salto de línea.
 
-#### **`include-markdown`**
-
-Incluye contenido de archivos Markdown, opcionalmente usando dos delimitadores
-para filtrar el contenido a incluir.
-
-- <a name="include-markdown_start" href="#include-markdown_start">#</a>
-**start**: Delimitador que marca el comienzo del contenido a incluir.
-- <a name="include-markdown_end" href="#include-markdown_end">#</a> **end**:
-Delimitador que marca el final del contenido a incluir.
-- <a name="include-markdown_preserve-includer-indent"
-href="#include-markdown_preserve-includer-indent">#</a>
-**preserve-includer-indent** (*true*): Cuando esta opción está habilitada (por
-defecto), cada línea del contenido a incluir es indentada con el mismo número de
-espacios usados para indentar la plantilla `{% %}` incluidora. Los valores
-posibles son `true` y `false`.
-- <a name="include-markdown_dedent" href="#include-markdown_dedent">#</a>
-**dedent** (*false*): Si se habilita, el contenido incluido será dedentado.
-- <a name="include-markdown_exclude" href="#include-markdown_exclude">#</a>
-**exclude**: Expecifica mediante un glob los archivos que deben ser ignorados.
-Sólo es útil pasando globs para incluir múltiples archivos.
-- <a name="include-markdown_trailing-newlines"
-href="#include-markdown_trailing-newlines">#</a> **trailing-newlines**
-(*true*): Cuando esta opción está deshabilitada, los saltos de línea finales que
-se encuentran en el contenido a incluir se eliminan. Los valores posibles son
-`true` y `false`.
-- <a name="include-markdown_recursive" href="#include-markdown_recursive">#</a>
-**recursive** (*true*): Cuando esta opción está deshabilitada, los archivos
-incluidos no son procesados para incluir de forma recursiva. Los valores
-posibles son `true` y `false`.
-- <a name="include-markdown_order" href="#include-markdown_order">#</a> **order**
-(*'alpha-path'*): Define el orden en el que múltiples archivos son incluidos
-al usar globs. Los valores posibles son:
+- <a name="include_start" href="#include_start">#</a> **start**: Delimitador que
+marca el comienzo del contenido a incluir.
+- <a name="include_end" href="#include_end">#</a> **end**: Delimitador que marca
+el final del contenido a incluir.
+- <a name="include_preserve-includer-indent"
+href="#include_preserve-includer-indent">#</a> **preserve-includer-indent**
+(*true*): Cuando esta opción está habilitada (por defecto), cada línea del
+contenido a incluir es indentada con el mismo número de espacios usados para
+indentar la plantilla `{% %}` incluidora. Los valores posibles son `true` y
+`false`.
+- <a name="include_dedent" href="#include_dedent">#</a> **dedent** (*false*): Si
+se habilita, el contenido incluido será dedentado.
+- <a name="include_exclude" href="#include_exclude">#</a> **exclude**: Especifica
+mediante un glob los archivos que deben ser ignorados. Sólo es útil pasando
+globs para incluir múltiples archivos.
+- <a name="include_trailing-newlines" href="#include_trailing-newlines">#</a>
+**trailing-newlines** (*true*): Cuando esta opción está deshabilitada, los
+saltos de línea finales que se encuentran en el contenido a incluir se eliminan.
+Los valores posibles son `true` y `false`.
+- <a name="include_recursive" href="#include_recursive">#</a> **recursive**
+(*true*): Cuando esta opción está deshabilitada, los archivos incluidos no son
+procesados para incluir de forma recursiva. Los valores posibles son `true` y
+`false`.
+- <a name="include_order" href="#include_order">#</a> **order** (*'alpha-path'*):
+Define el orden en el que múltiples archivos son incluidos al usar globs. Los
+posibles valores son:
    - Una combinación de un tipo de orden opcional y un sujeto de ordenación opcional
 separados por un guion (`-`), y opcionalmente precedidos por un guion (`-`)
 para indicar orden ascendente. Si no se especifica un tipo de orden o un sujeto
@@ -206,9 +202,15 @@ cambio de metadatos en sistemas Unix).
 no especificar ningún orden y confiar en el orden por defecto del sistema de
 archivos. Esto puede ser diferente entre sistemas operativos, así que úsalo con
 precaución.
-- <a name="include-markdown_encoding" href="#include-markdown_encoding">#</a>
-**encoding** (*'utf-8'*): Especifica la codificación del archivo incluído. Si
-no se define, se usará `'utf-8'`.
+- <a name="include_encoding" href="#include_encoding">#</a> **encoding**
+(*'utf-8'*): Especifica la codificación del archivo incluído. Si no se define,
+se usará `'utf-8'`.
+
+#### **`include-markdown`**
+
+Incluye contenido de archivos Markdown, opcionalmente usando dos delimitadores
+para filtrar el contenido a incluir.
+
 - <a name="include-markdown_rewrite-relative-urls"
 href="#include-markdown_rewrite-relative-urls">#</a> **rewrite-relative-urls**
 (*true*): Cuando esta opción está habilitada (por defecto), los enlaces e
@@ -285,62 +287,6 @@ especificado. Sólo soporta la sintaxis de encabezado de caracteres de hash
 
 Incluye el contenido de un archivo o un grupo de archivos.
 
-- <a name="include_start" href="#include_start">#</a> **start**: Delimitador que
-marca el comienzo del contenido a incluir.
-- <a name="include_end" href="#include_end">#</a> **end**: Delimitador que marca
-el final del contenido a incluir.
-- <a name="include_preserve-includer-indent"
-href="#include_preserve-includer-indent">#</a> **preserve-includer-indent**
-(*true*): Cuando esta opción está habilitada (por defecto), cada línea del
-contenido a incluir es indentada con el mismo número de espacios usados para
-indentar la plantilla `{% %}` incluidora. Los valores posibles son `true` y
-`false`.
-- <a name="include_dedent" href="#include_dedent">#</a> **dedent** (*false*): Si
-se habilita, el contenido incluido será dedentado.
-- <a name="include_exclude" href="#include_exclude">#</a> **exclude**: Especifica
-mediante un glob los archivos que deben ser ignorados. Sólo es útil pasando
-globs para incluir múltiples archivos.
-- <a name="include_trailing-newlines" href="#include_trailing-newlines">#</a>
-**trailing-newlines** (*true*): Cuando esta opción está deshabilitada, los
-saltos de línea finales que se encuentran en el contenido a incluir se eliminan.
-Los valores posibles son `true` y `false`.
-- <a name="include_recursive" href="#include_recursive">#</a> **recursive**
-(*true*): Cuando esta opción está deshabilitada, los archivos incluidos no son
-procesados para incluir de forma recursiva. Los valores posibles son `true` y
-`false`.
-- <a name="include_order" href="#include_order">#</a> **order** (*'alpha-path'*):
-Define el orden en el que múltiples archivos son incluidos al usar globs. Los
-posibles valores son:
-   - Una combinación de un tipo de orden opcional y un sujeto de ordenación opcional
-separados por un guion (`-`), y opcionalmente precedidos por un guion (`-`)
-para indicar orden ascendente. Si no se especifica un tipo de orden o un sujeto
-de ordenación, se usan los valores por defecto. Sigue la forma:
-`[-]<tipo_de_orden>-<sujeto_de_ordenación>` donde:
-      - **Tipo de orden**:
-         - `'alpha'` (por defecto): Orden alfabético.
-         - `'natural'`: Orden natural, de modo que por ejemplo `file2.md` va antes
-`file10.md`.
-      - **Sujeto de ordenación**:
-         - `'path'` (por defecto): Ordena por la ruta completa del archivo.
-         - `'name'`: Ordena sólo por el nombre del archivo.
-         - `'extension'`: Ordena por la extensión del archivo.
-   - Una combinación de un guion opcional al principio para denotar orden ascendente
-y uno de los siguientes valores en la forma `[-]<valor>` donde `<valor>` es
-uno de los siguientes:
-      - `'size'`: Ordena por el tamaño del archivo.
-      - `'mtime'`: Ordena por la hora de modificación del archivo.
-      - `'ctime'`: Ordena por la hora de creación del archivo (o la última hora de
-cambio de metadatos en sistemas Unix).
-      - `'atime'`: Ordena por la última hora de acceso al archivo.
-   - `'random'`: Orden aleatorio.
-   - `'system'`: Orden proporcionado por el sistema operativo. Esto es lo mismo que
-no especificar ningún orden y confiar en el orden por defecto del sistema de
-archivos. Esto puede ser diferente entre sistemas operativos, así que úsalo con
-precaución.
-- <a name="include_encoding" href="#include_encoding">#</a> **encoding**
-(*'utf-8'*): Especifica la codificación del archivo incluído. Si no se define,
-se usará `'utf-8'`.
-
 ##### Ejemplos
 
 ```jinja