Skip to content

Latest commit

 

History

History
298 lines (248 loc) · 10.5 KB

README.md

File metadata and controls

298 lines (248 loc) · 10.5 KB
Raw

mkdocs-include-markdown-plugin

PyPI License Tests Coverage status Downloads

Plugin de inclusiones Markdown para Mkdocs.

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

Configuración

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

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.

plugins:
  - include-markdown:
      encoding: ascii
      preserve_includer_indent: false
      dedent: false
      trailing_newlines: true
      comments: true
      rewrite_relative_urls: true
      heading_offset: 0
      start: <!--start-->
      end: <!--end-->
      recursive: true

opening_tag y closing_tag

Etiquetas de apertura y cierre por defecto. Cuando no se especifican son {% y %}.

plugins:
  - include-markdown:
      opening_tag: "{!"
      closing_tag: "!}"

exclude

Patrones de comodín de exclusión globales. Las rutas relativas definidas aquí serán relativas al directorio docs_dir.

plugins:
  - include-markdown:
      exclude:
        - LICENSE.md
        - api/**

cache

Tiempo de caducidad en segundos para las solicitudes HTTP almacenadas en caché al incluir desde URL.

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:

# 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 a incluir pueden ser:

  • URLs para incluir contenido remoto.
  • 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 ./docs/includes/header.md.
  • Patrones glob de Bash que coincidan con múltiples archivos locales.

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.
  • # 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.
  • # 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 (false): Cuando esta opción está habilitada, 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 'includes/header.md'
    start='<!--\n\ttable-start\n-->'
    end='<!--\n\ttable-end\n-->'
    rewrite-relative-urls=false
    comments=true
%}
{%
    include-markdown "includes/header.md"
    heading-offset=1
%}
{%
    include-markdown "../LICENSE*"
    start="<!--license \"start\" -->"
    end='<!--license "end" -->'
    exclude="../*.rst"
%}
{%
    include-markdown "**"
    exclude="./{index,LICENSE}.md"
%}
{% 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.
  • # 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.
  • # 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 '**'
    exclude='./*.md'
%}

Agradecimiento