web-dev-qa-db-fra.com

Markdown et y compris plusieurs fichiers

Existe-t-il une fourchette de démarques qui vous permet de référencer d’autres fichiers, comme un fichier d’inclusion? Plus précisément, je veux créer un fichier de démarquage distinct avec des liens que j’appelle souvent mais pas toujours (appelez ce B.md), puis lorsque je suis lié par référence dans le fichier md que j’écris (A.md), aimez-le pour tirer le lien de l'autre fichier (B.md) plutôt que de la fin du fichier actuel (A.md). 

markdown
142
David LaSpina

La réponse courte est non. La réponse longue est oui. :-)

Markdown a été conçu pour permettre aux utilisateurs d'écrire un texte simple, lisible et facilement convertible en un balisage HTML simple. Il ne fait pas vraiment la mise en page du document. Par exemple, il n’existe aucun moyen réel d’aligner une image à droite ou à gauche. En ce qui concerne votre question, il n’existe aucune commande de démarquage pour inclure un seul lien d’un fichier à un autre dans une version de démarquage (pour autant que je sache). 

Le plus proche de cette fonctionnalité est Pandoc . Pandoc vous permet de fusionner des fichiers dans le cadre de la transformation, ce qui vous permet de restituer facilement plusieurs fichiers en une seule sortie. Par exemple, si vous créez un livre, vous pouvez avoir des chapitres comme celui-ci:

01_preface.md
02_introduction.md
03_why_markdown_is_useful.md
04_limitations_of_markdown.md
05_conclusions.md

Vous pouvez les fusionner en exécutant cette commande dans le même répertoire:

pandoc *.md > markdown_book.html

Puisque pandoc fusionnera tous les fichiers avant de faire la traduction, vous pouvez inclure vos liens dans le dernier fichier comme ceci:

01_preface.md
02_introduction.md
03_why_markdown_is_useful.md
04_limitations_of_markdown.md
05_conclusions.md
06_links.md

Donc, une partie de votre 01_preface.md pourrait ressembler à ceci:

I always wanted to write a book with [markdown][mkdnlink].

Et une partie de votre 02_introduction.md pourrait ressembler à ceci:

Let's start digging into [the best text-based syntax][mkdnlink] available.

Tant que votre dernier fichier comprend la ligne:

[mkdnlink]: http://daringfireball.net/projects/markdown

... la même commande utilisée auparavant effectuera la fusion et la conversion tout en incluant ce lien. Assurez-vous simplement de laisser une ou deux lignes vides au début de ce fichier. La documentation pandoc indique qu'elle ajoute une ligne vierge entre les fichiers fusionnés de cette façon, mais que cela ne fonctionnait pas pour moi sans la ligne vierge.

172
Aaron Massey

Je voudrais simplement mentionner que vous pouvez utiliser la commande cat pour concaténer les fichiers d'entrée avant de les rediriger vers markdown_py, ce qui a le même effet que ce que pandoc fait avec plusieurs fichiers d'entrée entrants.

cat *.md | markdown_py > youroutputname.html

fonctionne à peu près de la même façon que l’exemple pandoc ci-dessus pour la version Python de Markdown sur mon Mac.

45
Marty Heyman

Vous pouvez réellement utiliser le préprocesseur de Markdown ( MarkdownPP ). En utilisant l'exemple de livre hypothétique des autres réponses, vous créeriez des fichiers .mdpp représentant vos chapitres. Les fichiers .mdpp peuvent ensuite utiliser la directive !INCLUDE "path/to/file.mdpp", qui remplace la directive de manière récursive par le contenu du fichier référencé dans la sortie finale.

chapters/preface.mdpp
chapters/introduction.mdpp
chapters/why_markdown_is_useful.mdpp
chapters/limitations_of_markdown.mdpp
chapters/conclusions.mdpp

Vous auriez alors besoin d'un index.mdpp contenant les éléments suivants:

!INCLUDE "chapters/preface.mdpp"
!INCLUDE "chapters/introduction.mdpp"
!INCLUDE "chapters/why_markdown_is_useful.mdpp"
!INCLUDE "chapters/limitations_of_markdown.mdpp"
!INCLUDE "chapters/conclusions.mdpp"

Pour rendre votre livre, vous devez simplement exécuter le préprocesseur sur index.mdpp:

$ markdown-pp.py index.mdpp mybook.md

N'oubliez pas de consulter le répertoire readme.mdpp dans le répertoire MarkdownPP pour une présentation des fonctionnalités du préprocesseur adaptées aux projets de documentation plus importants.

20
ninegrid

Ma solution est d'utiliser m4. Il est pris en charge sur la plupart des plates-formes et est inclus dans le package binutils.

Commencez par inclure une macro changequote() dans le fichier pour changer les caractères de citation en ce que vous préférez (la valeur par défaut est `'). La macro est supprimée lors du traitement du fichier. 

changequote(`{{', `}}')
include({{other_file}})

Sur la ligne de commande:

m4 -I./dir_containing_other_file/ input.md > _tmp.md
pandoc -o output.html _tmp.md
12
Ben Hochstedler

Récemment, j'ai écrit quelque chose comme ceci dans Node appelé markdown-include qui vous permet d'inclure des fichiers de démarques avec une syntaxe de style C, comme suit:

#include "my-file.md"

Je crois que cela s’aligne parfaitement avec la question que vous posez. Je connais ce vieux, mais je voulais au moins le mettre à jour.

Vous pouvez l'inclure dans n'importe quel fichier de démarques que vous souhaitez. Ce fichier peut également avoir plus d'inclusions et markdown-include créera un lien interne et effectuera tout le travail à votre place.

Vous pouvez le télécharger via npm

npm install -g markdown-include
11
Sethen

En fait, vous pouvez utiliser \input{filename} et \include{filename} qui sont des commandes latex, Directement dans Pandoc, car il supporte presque toute la syntaxe html et latex.

Mais attention, le fichier inclus sera traité comme un fichier latex. Mais vous pouvez facilement compiler votre markdown à latex avec Pandox.

3
Wung Hugh

Multimarkdown a cela nativement. Il l’appelle fichier transclusion :

{{some_other_file.txt}}

c'est tout ce qu'il faut. Nom étrange, mais coche toutes les cases.

2
eff

En fait, je suis surpris que personne sur cette page n’ait proposé de solutions HTML. Pour autant que je sache, les fichiers MarkDown peuvent inclure une grande partie (sinon la totalité) des balises HTML. Alors suivez ces étapes:

  1. From here : placez vos fichiers MarkDown dans les balises <span style="display:block"> ... </span> pour vous assurer qu’ils seront rendus sous forme de markdown. Vous avez beaucoup d'autres propriétés de style que vous pouvez ajouter. Celui que j'aime bien est le text-align:justify.

  2. De ici : Incluez les fichiers dans votre fichier principal en utilisant le <iframe src="/path/to/file.md" seamless></iframe>

P.S.1. cette solution ne fonctionne pas sur tous les moteurs/rendus MarkDown. Par exemple, Typora a rendu les fichiers correctement, mais pas le code Visual Studio. Ce serait formidable si d’autres pouvaient partager leur expérience avec d’autres plateformes. En particulier, j'aimerais entendre parler de GitHub et de GitLab ...

P.S.2. Il semble y avoir de gros problèmes d’incompatibilité au cours d’un examen plus approfondi, ce qui peut avoir pour conséquence que cet affichage n’est pas correctement rendu sur de nombreuses plates-formes, notamment Typora, GitHub et le code Visual Studio. S'il vous plaît ne l'utilisez pas jusqu'à ce que je les résolve. Je ne supprimerai pas la réponse uniquement pour des raisons de discussion et si vous pouviez peut-être partager vos opinions.

P.S.3. Pour approfondir ce problème, j'ai posé cette question ici sur StackOverflow et ici sur Reddit .

P.S.4. Après quelques études, je suis parvenu à la conclusion que pour le moment, AsciiDoc était une meilleure option pour la documentation. Il est livré avec la fonctionnalité d’inclusion intégrée, il est rendu par GitHub, et les principaux éditeurs de code comme Atom et vscode ont des extensions pour la prévisualisation en direct. On peut utiliser Pandoc ou d’autres outils pour convertir automatiquement le code MarkDown existant en AsciiDoc avec des modifications mineures.

P.S.5. Un autre langage de balisage léger avec une fonctionnalité d'inclusion intégrée est reStructuredText. Il est livré avec la syntaxe .. include:: inclusion.txt par norme. Il y a Editeur ReText avec aperçu en direct.

2
Foad

Je pense que nous ferions mieux de adopter une nouvelle syntaxe d'inclusion de fichier (pour ne pas gâcher les blocs de code Je pense que l'inclusion de style C est totalement fausse), et j'ai écrit un petit outil en Perl, nommé cat.pl , parce qu'il fonctionne comme cat (cat a.txt b.txt c.txt fusionnera trois fichiers ), mais il fusionne les fichiers en profondeur et non pas en largeur. . Comment utiliser?

$ Perl cat.pl <your file>

La syntaxe en détail est la suivante:

  • fichiers inclus récursifs: @include <-=path=
  • il suffit d'en inclure un: %include <-=path=

Il peut gérer correctement l’inclusion de fichiers loops (si a.txt <- b.txt, b.txt <- a.txt, qu’attendez-vous alors?).

Exemple:

a.txt:

a.txt

    a <- b

    @include <-=b.txt=

a.end

b.txt:

b.txt

    b <- a

    @include <-=a.txt=

b.end

Perl cat.pl a.txt > c.txt, c.txt:

a.txt

    a <- b

    b.txt

        b <- a

        a.txt

            a <- b

            @include <-=b.txt= (note：won't include, because it will lead to infinite loop.)

        a.end

    b.end

a.end

Plus d'exemples sur https://github.com/district10/cat/blob/master/tutorial_cat.pl_.md .

J'ai aussi écrit une version Java ayant un effet identique (pas le même, mais proche).

1
dvorak4tzx

Asciidoc ( http://www.methods.co.nz/asciidoc/ ) est en réalité une réduction des stéroïdes. Dans l’ensemble, Asciidoc et Markdown auront l’air très semblable et il est assez facile de changer de fournisseur. Un avantage de énorme d'Asciidoc par rapport au balisage, c'est qu'il prend déjà en charge les inclus, pour les autres fichiers Asciidoc, mais aussi pour tous les formats que vous aimez. Vous pouvez même inclure en partie des fichiers basés sur des numéros de ligne ou des balises dans vos fichiers inclus.

Inclure d'autres fichiers est vraiment un épargnant de vie lorsque vous écrivez des documents.

Vous pouvez par exemple avoir un fichier asciidoc avec un tel contenu:

// [source,Perl]
// ----
// include::script.pl[]
// ----

et maintenez votre échantillon dans script.pl

Et je suis sûr que vous vous demanderez alors oui, Github soutient également l’asciidoc.

0
Wilfried Kopp

J'utilise Marked 2 sur Mac OS X. Il prend en charge la syntaxe suivante pour inclure d'autres fichiers. 

<<[chapters/chapter1.md]
<<[chapters/chapter2.md]
<<[chapters/chapter3.md]
<<[chapters/chapter4.md]

Malheureusement, vous ne pouvez pas transmettre cela à pandoc car il ne comprend pas la syntaxe. Cependant, écrire un script pour éliminer la syntaxe et construire une ligne de commande pandoc est assez simple.

0
paxos1977