Skip to content

Latest commit

 

History

History
326 lines (269 loc) · 11.2 KB

README.md

File metadata and controls

326 lines (269 loc) · 11.2 KB

mkdocs-include-markdown-plugin

PyPI License Tests Coverage status Downloads

Plugin d'inclusion de Markdown pour Mkdocs.

Lire ce document dans d'autres langues:

Installation

pip install mkdocs-include-markdown-plugin

Documentation

Préparation

Activer le plugin dans votre fichier mkdocs.yml:

plugins:
  - include-markdown

Configuration

Le comportement global du plugin peut être personnalisé dans la configuration.

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.

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 et closing_tag

Balises d'ouverture et de fermeture par défaut. Lorsqu'elles ne sont pas spécifiées, elles sont {% et %}.

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

exclude

Modèles de globes d'exclusion globaux. Les chemins relatifs définis ici seront relatifs au répertoire docs_dir.

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

cache

Délai d'expiration en secondes pour les requêtes HTTP mises en cache lors de l'inclusion d'URL.

plugins:
  - include-markdown:
      cache: 600

Pour utiliser cette fonctionnalité, la dépendance platformdirs doit être installée ou le paramètre cache_dir doit être défini. Vous pouvez inclure platformdirs dans l'installation du plugin en ajoutant le supplément cache :

# requirements.txt
mkdocs-include-markdown-plugin[cache]

cache_dir

Répertoire dans lequel les requêtes HTTP mises en cache seront stockées. Si défini, platformdirs n'a pas besoin d'être installé pour utiliser cache.

plugins:
  - include-markdown:
      cache: 600
      cache_dir: ./mkdocs-include-markdown-cache

Un fichier .gitignore sera ajouté au répertoire de cache s'il n'existe pas pour éviter de valider les fichiers de cache.

directives

Personnaliser les noms des directives.

plugins:
  - include-markdown:
      directives:
        include-markdown: include-md
        include: replace

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 chemins des fichiers inclus peuvent être soit:

  • URL pour inclure du contenu distant.
  • 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 ./docs/, alors includes/header.md va correspondre au fichier ./docs/includes/header.md.
  • Globs génériques Bash correspondant à plusieurs fichiers locaux.

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 échappés en leur ajoutant un caractère \ comme \" et \'.

Les chaînes start et end peuvent contenir des séquences d'échappement habituelles (de style Python) telles que \n pour correspondre aux nouvelles lignes.

include-markdown

Inclut contenu des Markdown fichiers, en utilisant éventuellement deux délimiteurs pour filtrer le contenu à inclure.

  • # start: Délimiteur qui marque le début du contenu à inclure.
  • # end: Délimiteur qui marque la fin du contenu à inclure.
  • # preserve-includer-indent (true): Lorsque cette option est activée (par défaut), chaque ligne du contenu à inclure est indentée avec le même nombre d'espaces utilisé pour indenter l'incluseur modèle {% %}. Les valeurs possibles sont true et false.
  • # dedent (false): Lorsque est activée, le contenu inclus sera déchiqueté.
  • # exclude: Spécifiez avec un glob quels fichiers doivent être ignorés. Uniquement utile lors du passage de globs pour inclure plusieurs fichiers.
  • # trailing-newlines (true): Lorsque cette option est désactivée, les nouvelles lignes de fin trouvées dans le contenu à inclure sont supprimées. Les valeurs possibles sont true et false.
  • # recursive (true): Lorsque cette option est désactivée, les fichiers inclus ne sont pas traités pour des inclusions récursives. Les valeurs possibles sont true et false.
  • # encoding ('utf-8'): Spécifiez l'encodage du fichier inclus. S'il n'est pas défini, 'utf-8' sera utilisé.
  • # rewrite-relative-urls (true): Lorsque cette option est activée (par défaut), liens et images Markdown dans le contenu qui sont spécifiés par une URL relative sont réécrits pour fonctionner correctement dans leur nouvel emplacement. Les valeurs possibles sont true et false.
  • # comments (false): Lorsque cette option est activée, le contenu à inclure est entouré de <!-- BEGIN INCLUDE --> et <!-- END INCLUDE --> commentaires qui aident à identifier que le contenu a été inclus. Les valeurs possibles sont true et false.
  • # heading-offset (0): Augmente ou diminue la profondeur des en-têtes Markdown de ce nombre. Ne prend en charge que la syntaxe d'en-tête du signe dièse (#). Cet argument accepte les valeurs négatives pour supprimer les caractères # de tête.
Exemples
{%
    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

Inclus le contenu d'un fichier ou d'un groupe de fichiers.

  • # start: Délimiteur qui marque le début du contenu à inclure.
  • # end: Délimiteur qui marque la fin du contenu à inclure.
  • # preserve-includer-indent (true): Lorsque cette option est activée (par défaut), chaque ligne du contenu à inclure est indentée avec le même nombre d'espaces utilisé pour indenter l'incluseur modèle {% %}. Les valeurs possibles sont true et false.
  • # dedent (false): Lorsque est activée, le contenu inclus sera déchiqueté.
  • # exclude: Spécifiez avec un glob quels fichiers doivent être ignorés. Uniquement utile lors du passage de globs pour inclure plusieurs fichiers.
  • # trailing-newlines (true): Lorsque cette option est désactivée, les nouvelles lignes de fin trouvées dans le contenu à inclure sont supprimées. Les valeurs possibles sont true et false.
  • # recursive (true): Lorsque cette option est désactivée, les fichiers inclus ne sont pas traités pour des inclusions récursives. Les valeurs possibles sont true et false.
  • # encoding ('utf-8'): Spécifiez l'encodage du fichier inclus. S'il n'est pas défini, 'utf-8' sera utilisé.
Exemples
~~~yaml
{% include "../examples/github-minimal.yml" %}
~~~
    {%
        include "../examples.md"
        start="~~~yaml"
        end="~~~\n"
    %}
{%
    include '**'
    exclude='./*.md'
%}

Reconnaissance