Skip to content

Latest commit

 

History

History
223 lines (184 loc) · 8.18 KB

README.md

File metadata and controls

223 lines (184 loc) · 8.18 KB
Raw

mkdocs-include-markdown-plugin

Plugin de inclusiones Markdown para Mkdocs.

PyPI Tests Coverage status

Lee este documento en otros idiomas:

Instalación

pip install mkdocs-include-markdown-plugin

Documentación

Preparación

Habilita el plugin en tu mkdocs.yml:

plugins:
  - include-markdown

Asegúrate que defines include-markdown antes de otros plugins que pudieran entrar en conflicto, como mkdocs-macros-plugin.

Configuración

El comportamiento global del plugin puede ser personalizado en la configuración.

  • # opening_tag and 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.

plugins:
  - include-markdown:
      opening_tag: "{!"
      closing_tag: "!}"
      encoding: ascii
      preserve_includer_indent: false
      dedent: true
      trailing_newlines: false
      comments: false

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 archivo para incluir y los argumentos de cadena se pueden envolver con comillas dobles " o simples ', que se pueden escapar anteponiendo un carácter \ como \" y \'.

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.

  • # start: Delimitador que marca el comienzo del contenido a incluir.
  • # end: Delimitador que marca el final del contenido a incluir.
  • # 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.
  • # dedent (false): Si se habilita, el contenido incluido será dedentado.
  • # exclude: Expecifica mediante un glob los archivos que deben ser ignorados. Sólo es útil pasando globs para incluir múltiples archivos.
  • # 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.
  • # encoding (utf-8): Especifica la codificación del archivo incluído. Si no se define, se usará utf-8.
  • # rewrite-relative-urls (true): Cuando esta opción está habilitada (por defecto), los enlaces e imágenes Markdown en el contenido que están definidas mediante una URL relativa son rescritos para funcionar correctamente en su nueva localización. Los valores posibles son true y false.
  • # comments (true): Cuando esta opción está habilitada (por defecto), el contenido a incluir es envuelto por comentarios <!-- BEGIN INCLUDE --> y <!-- END INCLUDE --> que ayudan a identificar que el contenido ha sido incluido. Los valores posibles son true y false.
  • # heading-offset (0): Incrementa o disminuye la profundidad de encabezados Markdown por el número especificado. Sólo soporta la sintaxis de encabezado de caracteres de hash (#). Acepta valores negativos para eliminar caracteres # a la izquierda.
Ejemplos
{%
   include-markdown "../README.md"
   start="<!--intro-start-->"
   end="<!--intro-end-->"
%}
{%
   include-markdown 'docs/includes/header.md'
   start='<!--\n\ttable-start\n-->'
   end='<!--\n\ttable-end\n-->'
   rewrite-relative-urls=false
   comments=false
%}
{%
   include-markdown "docs/includes/header.md"
   heading-offset=1
%}
{%
   include-markdown "../LICENSE*"
   start="<!--license \"start\" -->"
   end='<!--license "end" -->'
   exclude="../LICENSE*.rst"
%}
{% include-markdown '/escap\'ed/single-quotes/in/file\'/name.md' %}

include

Incluye el contenido de un archivo o un grupo de archivos.

  • # start: Delimitador que marca el comienzo del contenido a incluir.
  • # end: Delimitador que marca el final del contenido a incluir.
  • # 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.
  • # dedent (false): Si se habilita, el contenido incluido será dedentado.
  • # exclude: Especifica mediante un glob los archivos que deben ser ignorados. Sólo es útil pasando globs para incluir múltiples archivos.
  • # 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.
  • # encoding (utf-8): Especifica la codificación del archivo incluído. Si no se define, se usará utf-8.
Ejemplos
~~~yaml
{% include "../examples/github-minimal.yml" %}
~~~
    {%
      include "../examples.md"
      start="~~~yaml"
      end="~~~\n"
    %}
{%
   include '../LICENSE*'
   exclude='../LICENSE*.rst'
%}

Agradecimiento