Markdown et comprenant plusieurs fichiers

197

Y a-t-il une fourchette de démarque qui vous permet de référencer d'autres fichiers, quelque chose comme un fichier inclus? Plus précisément, je veux créer un fichier de démarque séparé avec des liens que j'appelle souvent mais pas toujours (appelez ce B.md), puis lorsque je lie par référence dans le fichier md que j'écris (A.md), je comme pour tirer le lien de l'autre fichier (B.md) plutôt que de la fin du fichier actuel (A.md).

David LaSpina
la source
1
Si votre question concerne le démarquage lié à github, vous pouvez jeter un œil ici
Adi Prasetyo
3
La règle de base pour Markdown est que la réponse à «Peut Markdown ...» est généralement «Pas pratiquement, universellement ou facilement».
Michael Scheper
4
Il y a une discussion ouverte sur la meilleure façon de le faire avec Pandoc sur github.com/jgm/pandoc/issues/553 et sur le forum commonmark
naught101

Réponses:

217

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

Markdown a été conçu pour permettre aux gens d'écrire du texte simple et lisible qui pourrait être facilement converti en un simple balisage HTML. 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. Quant à votre question, il n'y a pas de commande markdown pour inclure un seul lien d'un fichier à un autre dans n'importe quelle version de markdown (pour autant que je sache).

Pandoc est le plus proche de cette fonctionnalité . Pandoc vous permet de fusionner des fichiers dans le cadre de la transformation, ce qui vous permet de rendre 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

Étant donné que 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.mdpourrait ressembler à ceci:

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

Et une partie de votre 02_introduction.mdpourrait 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 tout au long. 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 vide entre les fichiers qui sont fusionnés de cette façon, mais cela n'a pas fonctionné pour moi sans la ligne vide.

Aaron Massey
la source
6
Cela s'avère être un article extrêmement utile pour moi! Merci Aaron. Il semble que ce serait un cas d'utilisation courant d'avoir un répertoire / chapitres, un script qui crée / fusionne des chapitres, puis un script d'encapsulation de niveau supérieur qui comprend une étape comme: --include-before-body $ (include_dir) / merged_chapters .html. C'est l'approche que je vais adopter pour obtenir des avantages organisationnels.
Rob
1
Un autre avantage de l'utilisation de pandoc est qu'il prend en charge une grande variété de sorties: vous pouvez générer non seulement du HTML mais aussi tout, de docx à LaTeX en passant par ePUB.
Chris Krycho
pandoc *.md > markdown_book.htmlrésulte en pandoc: *.md: openfile: invalid argument (Invalid argument)- il ne semble pas prendre en charge la syntaxe que vous avez spécifiée.
Jason Young
Il fonctionne sur mon système. J'ai créé un exemple de référentiel sur GitHub afin que vous puissiez l'essayer avec tous les fichiers que j'ai utilisés.
Aaron Massey
Vous pouvez aligner les images correctement en incluant du CSS approprié, c'est ainsi que vous devriez probablement faire les choses de toute façon.
naught101
50

Je voudrais simplement mentionner que vous pouvez utiliser la catcommande pour concaténer les fichiers d'entrée avant de les canaliser, ce markdown_pyqui a le même effet que ce qui se pandocpasse avec plusieurs fichiers d'entrée.

cat *.md | markdown_py > youroutputname.html

fonctionne à peu près comme l' exemple pandoc ci-dessus pour la version Python de Markdown sur mon Mac.

Marty Heyman
la source
1
@ tprk77: sauf que la réponse d'Aaron indique clairement que la commande cat est redondante ici ..
naught101
1
L'utilisation de cat *.mdimplique une convention de nommage de fichier inflexible. Non seulement cette convention interdirait nécessairement les inclusions récursives, mais pour les projets de documentation plus volumineux, il serait difficile d'ajouter de nouveaux fichiers dans le mix. Il faudrait faire beaucoup de comptage et renommer. Le projet de démarque dispose d'un préprocesseur à cet effet depuis l'année 2010.
ninegrid
@ninegrid Bien que MarkdownPP semble très utile, en regardant le référentiel source auquel vous avez fait référence dans votre réponse, il me semble (a) MarkdownPP est le projet de John Reese uniquement; (b) il ne fait pas partie du "projet de démarque" (aucune des différentes saveurs); et (c) MarkdownPP génère GFM, en particulier. Correct? Comme je l'ai dit, cela semble intéressant et utile, mais votre commentaire ici donne l'impression que c'est une fonctionnalité Markdown standard que chaque implémentation Markdown devrait accompagner. Mais en regardant le repo, la situation semble être tout le contraire.
FeRD
Ne parvient pas à convertir les tableaux MD en tableaux HTML.
james.garriss
30

Vous pouvez réellement utiliser le préprocesseur Markdown ( MarkdownPP ). En utilisant l'exemple de livre hypothétique des autres réponses, vous créez des .mdppfichiers représentant vos chapitres. Les .mdppfichiers peuvent ensuite utiliser la !INCLUDE "path/to/file.mdpp"directive, qui fonctionne de manière récursive en remplaçant la directive 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.mdppqui contenait 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 exécutez simplement le préprocesseur sur index.mdpp:

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

N'oubliez pas de consulter le readme.mdppdans le référentiel MarkdownPP pour une présentation des fonctionnalités du préprocesseur adaptées aux projets de documentation plus volumineux.

ninegrid
la source
19

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 guillemets 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
Ben Hochstedler
la source
2
m4est à peine connu, mais est en effet un outil incroyablement puissant en ce qui concerne ces besoins d'inclusion génériques. Assez pour que la documentation mentionne qu'elle peut être "assez addictive".
Uriel
Maintenant, c'est une solution! Genius
Brandt
+1 pour l'idée et rappel de m4 ! Le plus drôle, c'est que lorsque j'ai vu les extensions ci-dessus comme «md», je pensais dans ma tête de m4 . Que vous incluiez ensuite un exemple est formidable. Je ne sais pas si cette question demande exactement ce que je recherche, mais cela pourrait faire l'affaire. Merci de toute façon.
Pryftan
15

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

#include "my-file.md"

Je pense que cela correspond bien à la question que vous posez. Je sais que c'est un ancien, mais je voulais au moins le mettre à jour.

Vous pouvez l'inclure dans n'importe quel fichier de démarque que vous souhaitez. Ce fichier peut également avoir plus d'includes et markdown-include fera un lien interne et fera tout le travail pour vous.

Vous pouvez le télécharger via npm

npm install -g markdown-include
Sethen
la source
1
Cela a été d'une grande aide! Je vous remercie!
leas
@leas Heureux d'être au service ... Je n'y ai pas travaillé depuis quelques années mais je veux toujours y revenir à un moment donné. Espérons que cela fonctionne bien pour vos besoins.
Sethen
9

Multimarkdown a cela nativement. Il appelle cela la transclusion de fichiers :

{{some_other_file.txt}}

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

eff
la source
existe-t-il des éditeurs libres et open source pour rendre cette syntaxe? J'ai posé cette question ici avec plus de détails. J'apprécierais si vous pouviez m'aider.
Foad
1
@Foad: J'ai bien peur d'être un utilisateur de Vim et je ne connais aucun de ces éditeurs. Je vois sur votre reddit Q que vous avez constaté que Asciidoc, et divers éditeurs de, soutiennent cela. Je ne savais pas cela - merci.
eff
Heureux que cela ait été utile. Mais vim a-t-il un aperçu en direct pour MultiMarkDown? seriez-vous gentil de partager votre configuration et vos fichiers dot avec plus de détails?
Foad
1
Pas d'aperçu en direct, je ne suis pas ce genre de gars. ;) La principale raison pour laquelle j'ai utilisé le démarquage était parce qu'il vise à être lisible par l'homme lorsqu'il n'est pas traité, donc je ne me soucie pas trop des aperçus (même si je comprends pourquoi les autres le font). La seule chose qui m'intéresse, dans ce cas, est la mise en évidence de la syntaxe, et la mise en évidence de la syntaxe de marquage par défaut fonctionne assez bien pour moi. Désolé de ne pas vous être plus utile.
eff
1
Il semble que cela pourrait être intéressant, bien que je ne vois aucune raison de le choisir plutôt que markdown / asciidoc à mes fins (maigres), au moins.
eff
8

J'utilise un includes.txtfichier avec tous mes fichiers dans le bon ordre, j'exécute pandoc comme ceci:

pandoc -s $(cat includes.txt) --quiet -f markdown -t html5 --css pandoc.css -o index.html

Fonctionne comme un charme!

Mike Mitterer
la source
1
Excellente approche . La spécification de l'ordre des fichiers est fondamentale, mais elle n'est accomplie avec les globméthodes que si vous numérotez les fichiers.
ephsmith
Pourriez-vous inclure une explication des étapes? Semble si puissant! Je voudrais savoir s'il est possible de le réduire pour effectuer d'autres conversions telles que .pdf et .tex.
nilon
6

En fait, vous pouvez utiliser \input{filename} et \include{filename}qui sont des commandes latex, directement dans Pandoc, car il prend en charge presque tout htmlet la latexsyntaxe.

Mais attention, le fichier inclus sera traité comme un latexfichier. Mais vous pouvez compiler votre markdownà latexavec Pandoxfacilement.

Wung Hugh
la source
6

Asciidoc ( http://www.methods.co.nz/asciidoc/ ) est en fait une démarque sur les stéroïdes. Dans l'ensemble, Asciidoc et Markdown seront très similaires et il est assez facile de changer. Un énorme avantage d'Asciidoc sur le démarquage est qu'il prend déjà en charge les inclusions, pour d'autres fichiers Asciidoc mais aussi pour tout format 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.

L'inclusion 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 conservez votre échantillon dans script.pl

Et je suis sûr que vous vous demanderez si oui, Github prend également en charge l'asciidoc.

Wilfried Kopp
la source
Il semble y avoir une belle promesse ici, mais ne donne pas de réponse complète avec les étapes à suivre. Est-il possible d'indiquer comment convertir le document multi-fichiers en un seul?
nilon le
C'est la meilleure solution sur cette page jusqu'à présent. Je suis arrivé à cette conclusion et j'ai abordé le problème ici sur Reddit . AsciiDoc a intégré inclure et il est rendu par GitHub. Atom et vscode ont tous deux de beaux plugins pour un aperçu en direct aussi. Je me demande pourquoi AsciiDoc n'est pas déjà la norme de l'industrie!
Foad
4

Je pense que nous devrions mieux adopter une nouvelle syntaxe d'inclusion de fichiers (donc ne gâcherons pas les blocs de code, je pense que l'inclusion de style C est totalement fausse), et j'ai écrit un petit outil en Perl, le nommage cat.pl, car il fonctionne commecat ( cat a.txt b.txt c.txtfusionnera trois fichiers), mais il fusionne les fichiers en profondeur , pas en largeur . Comment utiliser?

$ perl cat.pl <your file>

La syntaxe en détail est:

  • fichiers d'inclusion récursifs: @include <-=path=
  • n'en inclure qu'un: %include <-=path=

Il peut gérer correctement les boucles d' inclusion de fichiers (si a.txt <- b.txt, b.txt <- a.txt, alors ce que vous attendez?).

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 également écrit une version Java ayant un effet identique (pas le même, mais proche).

dvorak4tzx
la source
<<[include_file.md](Marqué 2 sur macOS): gist.github.com/district10/d46a0e207d888d0526aef94fb8d8998c
dvorak4tzx
A noter, @est utilisé pour les citations avec pandoc-citeproc(par exemple " @Darwin1859").
PlasmaBinturong
4

Je suis en fait surpris que personne sur cette page n'ait proposé de solutions HTML. Pour autant que j'ai compris, les fichiers MarkDown peuvent inclure une grande partie (sinon la totalité) des balises HTML. Suivez donc ces étapes:

  1. À partir d' ici : mettez vos fichiers MarkDown dans des <span style="display:block"> ... </span>balises pour vous assurer qu'ils seront rendus sous forme de démarque. Vous avez beaucoup d'autres propriétés de style que vous pouvez ajouter. Celui que j'aime est le text-align:justify.

  2. À partir d' ici : incluez les fichiers dans votre fichier principal à l'aide du<iframe src="/path/to/file.md" seamless></iframe>

PS1. cette solution ne fonctionne pas sur tous les moteurs / rendus MarkDown. Par exemple, Typora a rendu correctement les fichiers, mais pas Visual Studio Code. Ce serait formidable si d'autres pouvaient partager leur expérience avec d'autres plateformes. Je voudrais en particulier entendre parler de GitHub et GitLab ...

PS2. Après une enquête plus approfondie, il semble y avoir des problèmes d'incompatibilité majeurs conduisant à ce que cela ne soit pas correctement rendu sur de nombreuses plates-formes, y compris le code Typora, GitHub et Visual Studio. Veuillez ne pas l'utiliser jusqu'à ce que je les résolve. Je ne supprimerai pas la réponse juste pour le plaisir de la discussion et si vous pouvez peut-être partager vos opinions.

PS3. Pour approfondir ce problème, j'ai posé ces questions ici sur StackOverflow et ici sur Reddit .

PS4. Après quelques études approfondies, je suis parvenu à la conclusion que pour le moment, AsciiDoc est une meilleure option pour la documentation. Il est livré avec une fonctionnalité incluse intégrée, il est rendu par GitHub, et les principaux éditeurs de code comme Atom et vscode ont des extensions pour l'aperçu en direct. On peut utiliser Pandoc ou d'autres outils pour convertir automatiquement le code MarkDown existant en AsciiDoc avec des modifications mineures.

PS5. Un autre langage de balisage léger avec fonctionnalité intégrée intégrée est reStructuredText. Il est livré avec la .. include:: inclusion.txt syntaxe par défaut. Il existe également un éditeur ReText avec aperçu en direct.

Foad
la source
1

Je sais que c'est une vieille question, mais je n'ai vu aucune réponse à cet effet: Essentiellement, si vous utilisez markdown et pandoc pour convertir votre fichier en pdf, dans vos données yaml en haut de la page, vous pouvez inclure quelque chose comme ça:

---
header-includes:
- \usepackage{pdfpages}
output: pdf_document
---

\includepdf{/path/to/pdf/document.pdf}

# Section

Blah blah

## Section 

Blah blah

Depuis que pandoc utilise du latex pour convertir tous vos documents, la header-includessection appelle le package pdfpages. Ensuite, lorsque vous l'incluez, \includepdf{/path/to/pdf/document.pdf}il insère tout ce qui est inclus dans ce document. De plus, vous pouvez inclure plusieurs fichiers pdf de cette façon.

Comme bonus amusant, et c'est uniquement parce que j'utilise souvent le démarque, si vous souhaitez inclure des fichiers autres que le démarque, par exemple des fichiers en latex. J'ai quelque peu modifié cette réponse . Supposons que vous ayez un fichier de démarques markdown1.md:

---
title: Something meaning full
author: Talking head
---

Et deux fichiers latex supplémentaires document1, qui ressemble à ceci:

\section{Section}

Profundity.

\subsection{Section}

Razor's edge.

Et un autre, document2.tex, qui ressemble à ceci:

\section{Section

Glah

\subsection{Section}

Balh Balh

En supposant que vous souhaitiez inclure document1.tex et document2.tex dans markdown1.md, vous le feriez simplement pour markdown1.md

---
title: Something meaning full
author: Talking head
---

\input{/path/to/document1}
\input{/path/to/document2}

Exécutez pandoc dessus, par exemple

dans le terminal pandoc markdown1.md -o markdown1.pdf

Votre document final ressemblera un peu à ceci:

Quelque chose qui signifie plein

Tête parlante

Section

Profondeur.

Section

Le fil du rasoir.

Section

Glah

Section

Balh Balh

redapemusic35
la source
0

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 envoyer cela à pandoc car il ne comprend pas la syntaxe. Cependant, l'écriture d'un script pour supprimer la syntaxe pour construire une ligne de commande pandoc est assez facile.

paxos1977
la source
7
arriveriez-vous à avoir le script au lieu de simplement dire que c'est facile? :)
toobulkeh
0

Une autre solution côté client basée sur HTML utilisant markdown-it et jQuery . Vous trouverez ci-dessous un petit wrapper HTML en tant que document maître, qui prend en charge des inclusions illimitées de fichiers de démarques, mais pas des inclusions imbriquées. Une explication est fournie dans les commentaires JS. La gestion des erreurs est omise.

<script src="/markdown-it.min.js"></script>
<script src="/jquery-3.5.1.min.js"></script>

<script> 
  $(function() {
    var mdit = window.markdownit();
    mdit.options.html=true;
    // Process all div elements of class include.  Follow up with custom callback
    $('div.include').each( function() {
      var inc = $(this);
      // Use contents between div tag as the file to be included from server
      var filename = inc.html();
      // Unable to intercept load() contents.  post-process markdown rendering with callback
      inc.load(filename, function () {
        inc.html( mdit.render(this.innerHTML) );
      });
  });
})
</script>
</head>

<body>
<h1>Master Document </h1>

<h1>Section 1</h1>
<div class="include">sec_1.md</div>
<hr/>
<h1>Section 2</h1>
<div class="include">sec_2.md</div>
David Clarke
la source
-5

À mon humble avis, vous pouvez obtenir votre résultat en concaténant vos fichiers d'entrée * .md comme:

$ pandoc -s -o outputDoc.pdf inputDoc1.md inputDoc2.md outputDoc3.md
variable
la source