Уценка и в том числе несколько файлов
Есть ли какой-нибудь форк уценки, который позволяет ссылаться на другие файлы, что-то вроде включаемого файла? В частности, я хочу создать отдельный файл разметки со ссылками, которые я называю часто, но не всегда (назовите это B.md), затем, когда я делаю ссылку по ссылке в файле md, который я пишу (A.md), я бы например, чтобы получить ссылку из другого файла (B.md), а не из конца текущего файла (A.md).
20 ответов
Краткий ответ: нет. Длинный ответ - да.:-)
Разметка была разработана, чтобы позволить людям писать простой, читаемый текст, который можно легко преобразовать в простую HTML-разметку. Это действительно не делает макет документа. Например, нет реального способа выровнять изображение вправо или влево. Что касается вашего вопроса, нет команды markdown, которая бы включала одну ссылку из одного файла в другой в любой версии markdown (насколько я знаю).
Наиболее близким к этой функциональности может быть Pandoc. Pandoc позволяет объединять файлы как часть преобразования, что позволяет легко отображать несколько файлов в один вывод. Например, если вы создавали книгу, у вас могли бы быть такие главы:
01_preface.md
02_introduction.md
03_why_markdown_is_useful.md
04_limitations_of_markdown.md
05_conclusions.md
Вы можете объединить их, выполнив эту команду в том же каталоге:
pandoc *.md > markdown_book.html
Поскольку pandoc объединит все файлы перед выполнением перевода, вы можете включить свои ссылки в последний файл, например так:
01_preface.md
02_introduction.md
03_why_markdown_is_useful.md
04_limitations_of_markdown.md
05_conclusions.md
06_links.md
Так что часть вашего 01_preface.md может выглядеть так:
I always wanted to write a book with [markdown][mkdnlink].
И часть вашего 02_introduction.md может выглядеть так:
Let's start digging into [the best text-based syntax][mkdnlink] available.
Пока ваш последний файл содержит строку:
[mkdnlink]: http://daringfireball.net/projects/markdown
... та же команда, что использовалась ранее, будет выполнять слияние и преобразование, включая эту ссылку. Просто убедитесь, что вы оставили пустую строку или две в начале этого файла. Документация Pandoc говорит, что она добавляет пустую строку между файлами, которые объединяются таким образом, но это не сработало для меня без пустой строки.
Я бы сказал, что вы можете использовать cat Команда объединить входные файлы перед передачей их в markdown_py который имеет тот же эффект, что и что pandoc делает с несколькими входными файлами, поступающими.
cat *.md | markdown_py > youroutputname.html
работает почти так же, как и пример pandoc выше для версии Markdown для Python на моем Mac.
Вы можете использовать препроцессор Markdown( MarkdownPP). Работая с примером гипотетической книги из других ответов, вы бы создали .mdpp файлы, представляющие ваши главы..mdppфайлы могут затем использовать!INCLUDE "path/to/file.mdpp"директива, которая действует рекурсивно, заменяя директиву содержимым ссылочного файла в конечном выводе.
chapters/preface.mdpp
chapters/introduction.mdpp
chapters/why_markdown_is_useful.mdpp
chapters/limitations_of_markdown.mdpp
chapters/conclusions.mdpp
Вам тогда понадобитсяindex.mdppэто содержало следующее:
!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"
Для рендеринга вашей книги вы просто запускаете препроцессор наindex.mdpp:
$ markdown-pp.py index.mdpp mybook.md
Не забудьте посмотреть наreadme.mdpp в репозитории MarkdownPP для ознакомления с возможностями препроцессора, подходящими для больших проектов документации.
Мое решение состоит в том, чтобы использовать m4. Он поддерживается на большинстве платформ и входит в пакет binutils.
Сначала включите макрос changequote() в файле, чтобы изменить символы цитирования на то, что вы предпочитаете (по умолчанию `'). Макрос удаляется при обработке файла.
changequote(`{{', `}}')
include({{other_file}})
В командной строке:
m4 -I./dir_containing_other_file/ input.md > _tmp.md
pandoc -o output.html _tmp.md
Я использую includes.txt файл со всеми моими файлами в правильном порядке, я выполняю pandoc следующим образом:
pandoc -s $(cat includes.txt) --quiet -f markdown -t html5 --css pandoc.css -o index.html
Работает как шарм!
Совсем недавно я написал что-то вроде этого в Node под названием markdown-include, что позволяет вам включать файлы уценки с синтаксисом в стиле C, например:
#include "my-file.md"
Я считаю, что это хорошо согласуется с вопросом, который вы задаете. Я знаю, что это старый, но я хотел обновить его по крайней мере.
Вы можете включить это в любой файл уценки, который вы хотите. Этот файл также может иметь больше включений, а markdown-include создаст внутреннюю ссылку и сделает всю работу за вас.
Вы можете скачать его через npm
npm install -g markdown-include
Multimarkdown имеет это изначально. Это называет это включением файла:
{{some_other_file.txt}}
это все, что нужно. Странное имя, но все галочки отмечены галочкой.
Asciidoc ( http://www.methods.co.nz/asciidoc/) на самом деле является скидкой на стероиды. В целом, Asciidoc и Markdown будут выглядеть очень похоже, и их будет довольно легко переключать. Огромным преимуществом Asciidoc перед уценкой является то, что он поддерживает уже включенные, для других файлов Asciidoc, но также для любого формата, который вам нравится. Вы даже можете частично включать файлы на основе номеров строк или тегов внутри включенных файлов.
Включение других файлов действительно спасает жизнь, когда вы пишете документы.
Например, вы можете получить файл asciidoc с таким содержимым:
// [source,perl]
// ----
// include::script.pl[]
// ----
и сохранить ваш образец в script.pl
И я уверен, что вам будет интересно, так что да, Github также поддерживает Asciidoc.
На самом деле вы можете использовать \input{filename} а также \include{filename} которые являются латексными командами, прямо в Pandocпотому что он поддерживает почти все html а также latex синтаксис.
Но будьте осторожны, включенный файл будет рассматриваться как latex файл. Но вы можете собрать markdown в latex с Pandox без труда.
Синтаксис @import поддерживается в vscode-markdown-preview-Enhanced.
https://github.com/shd101wyy/vscode-markdown-preview-enhanced
что, вероятно, означает его часть основного инструмента mume
https://github.com/shd101wyy/mume
и другие инструменты, созданные на основе mume
Я знаю, что это старый вопрос, но я не видел ответов на этот вопрос: по сути, если вы используете markdown и pandoc для преобразования вашего файла в pdf, в ваши данные yaml вверху страницы вы можете включить что-то вроде этого:
---
header-includes:
- \usepackage{pdfpages}
output: pdf_document
---
\includepdf{/path/to/pdf/document.pdf}
# Section
Blah blah
## Section
Blah blah
Поскольку pandoc использует латекс для преобразования всех ваших документов, header-includessection вызывает пакет pdfpages. Затем, когда вы включаете\includepdf{/path/to/pdf/document.pdf}он вставит все, что включено в этот документ. Кроме того, таким образом вы можете включить несколько файлов PDF.
В качестве забавного бонуса, и это только потому, что я часто использую уценку, если вы хотите включить файлы, отличные от уценки, например латексные файлы. Я несколько изменил этот ответ. Скажем, у вас есть файл уценки markdown1.md:
---
title: Something meaning full
author: Talking head
---
И два дополнительных латексных файла document1, которые выглядят так:
\section{Section}
Profundity.
\subsection{Section}
Razor's edge.
И еще один документ, document2.tex, который выглядит так:
\section{Section
Glah
\subsection{Section}
Balh Balh
Предполагая, что вы хотите включить document1.tex и document2.tex в markdown1.md, вы просто сделаете это для markdown1.md
---
title: Something meaning full
author: Talking head
---
\input{/path/to/document1}
\input{/path/to/document2}
Запустите pandoc, например
в терминале pandoc markdown1.md -o markdown1.pdf
Ваш окончательный документ будет выглядеть примерно так:
Что-то означает полный
Говорящая голова
Раздел
Глубина.
Раздел
Лезвие бритвы.
Раздел
Glah
Раздел
Балх Балх
Я на самом деле удивлен, что никто на этой странице не предлагал никаких HTML-решений. Насколько я понял, файлы MarkDown могут включать в себя большую часть (если не все) тегов HTML. Так что следуйте этим шагам:
Отсюда: поместите ваши файлы MarkDown в
<span style="display:block"> ... </span>теги, чтобы убедиться, что они будут отображены как уценка. У вас есть множество других стилевых свойств, которые вы можете добавить. Тот, который мне нравится, этоtext-align:justify,Отсюда: включите файлы в ваш основной файл, используя
<iframe src="/path/to/file.md" seamless></iframe>
PS1. Это решение не работает на всех движках / рендерах MarkDown. Например, Typora правильно отображала файлы, а код Visual Studio - нет. Было бы здорово, если бы другие могли поделиться своим опытом с другими платформами. Особенно хотелось бы услышать о GitHub и GitLab...
PS2. При дальнейшем исследовании, как представляется, возникают серьезные проблемы несовместимости, которые приводят к тому, что это неправильно отображается на многих платформах, включая Typora, GitHub и код Visual Studio. Пожалуйста, не используйте это, пока я не разрешаю их. Я не буду удалять ответ только ради обсуждения и, если возможно, вы можете поделиться своим мнением.
PS3. Для дальнейшего изучения этой проблемы я задавал эти вопросы здесь, в Stackru и здесь, в Reddit.
PS4. После некоторого изучения я пришел к выводу, что на данный момент AsciiDoc является лучшим вариантом для документации. Он поставляется со встроенной функцией включения, он обрабатывается GitHub, а основные редакторы кода, такие как Atom и vscode, имеют расширения для предварительного просмотра в реальном времени. Можно использовать Pandoc или другие инструменты для автоматического преобразования существующего кода MarkDown в AsciiDoc с небольшими изменениями.
ПС5. Другой легкий язык разметки со встроенной функцией включения reStructuredText, Идет с .. include:: inclusion.txt
синтаксис по стандарту. Также есть редактор ReText с предварительным просмотром.
Я думаю, что нам лучше принять новый синтаксис включения файлов (так что не стоит путаться с блоками кода, я думаю, что включение в стиле C совершенно неправильно), и я написал небольшой инструмент на Perl, называя cat.pl потому что это работает как cat (cat a.txt b.txt c.txt объединит три файла), но объединит файлы по глубине, а не по ширине. Как пользоваться?
$ perl cat.pl <your file>
Синтаксис в деталях:
- рекурсивные включаемые файлы:
@include <-=path= - просто включите один:
%include <-=path=
Он может правильно обрабатывать циклы включения файлов (если a.txt <- b.txt, b.txt <- a.txt, то чего вы ожидаете?).
Пример:
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
Дополнительные примеры на https://github.com/district10/cat/blob/master/tutorial_cat.pl_.md.
Я также написал версию Java, имеющую идентичный эффект (не такой же, но близкий).
Если вы используете pandoc для обработки уценки, пока нет собственного решения (обсуждается в https://github.com/jgm/pandoc/issues/553), за исключением использования более одного входного файла уценки при вызове
pandoc.
Однако с помощью codebraid (на самом деле предназначенного для включения автоматически сгенерированного контента в Markdown) этого можно достичь:
This is the content of the main Markdown file `main.md`.
Below this line, the content of the file `chapter01.md` is included:
```{.python .cb.run}
with open('chapter01.md') as fp:
print(fp.read())
```
This line is printed below the external content.
Чтобы преобразовать его в любой выходной формат, используйте что-то вроде следующего:
codebraid pandoc main.md --to markdown
Хотя codebraid может считаться излишним, если "просто" включать внешние файлы Markdown, он позволяет гораздо больше, например, включение таблиц CSV или Excel из внешних источников:
Details are shown in the following table:
```{.python .cb.run}
import pandas as pd
table = pd.read_csv('table.csv')
print(talbe.to_markdown())
```
Вдохновленный ответом @Oliver Matthews, вы можете создать Perl-скрипт, который рекурсивно ищет синтаксис![[B.md]]и замените его наB.mdсодержание
Давайте создадим рекурсивный скрипт с именемparseMd.sh
#!/usr/bin/env bash
perl -ne 's#^!\[\[(.+?)\]\].*#`'$0' "$1"`#e;print' "$@"
и использовать его так
./parseMd.sh A.md > result.md
Использование его с pandoc для экспорта в pdf
pandoc <(./parseMd.sh A.md) -o result.pdf
Еще одно клиентское решение на основе HTML с использованием markdown-it и jQuery. Ниже представлена небольшая HTML-оболочка в качестве главного документа, которая поддерживает неограниченное количество включений файлов уценки, но не вложенных. Объяснение дается в комментариях JS. Обработка ошибок опущена.
<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>
Я знаю, что было бы удобно, если бы эту функцию можно было реализовать. Работа со строительными инструментами, такими какMakefile, можно было бы добавлять или обновлять таблицы и автоматически генерировать большие и сложные документы и отчеты.
Поэтому я написал один сам, и я надеюсь, что он будет полезен для всех вас :)
Я использую Marked 2 в Mac OS X. Он поддерживает следующий синтаксис для включения других файлов.
<<[chapters/chapter1.md]
<<[chapters/chapter2.md]
<<[chapters/chapter3.md]
<<[chapters/chapter4.md]
К сожалению, вы не можете передать это Пандоку, так как он не понимает синтаксис. Тем не менее, написание сценария для удаления синтаксиса для построения командной строки pandoc достаточно просто.
ИМХО, Вы можете получить свой результат, объединив свои входные *.md файлы, такие как:
$ pandoc -s -o outputDoc.pdf inputDoc1.md inputDoc2.md outputDoc3.md
Переключитесь на asciidoc, чтобы вам не приходилось работать с таким языком, как Markdown, который в наши дни очень примитивен :)