В pandoc есть способ включить имя файла поверх блоков кода?

Question

Я работаю над документом в уценке (использую pandoc для генерации окончательного документа) и хотел бы иметь блоки кода, показывающие выдержки из файлов. Я хотел бы, чтобы имя файла располагалось поверх блока кода, примерно так:

Я искал документацию Pandoc, но не смогничего не найти.

Answer 1

Один из методов - использовать атрибуты и пользовательский CSS, например:

<style>
div.sourceCode::before {
    content: attr(data-filename);
    display: block;
    background-color: #cfeadd;
    font-family: monospace;
}
</style>

``` {.python filename="ch1/test_one.py"}
def test_passing():
    assert (1, 2, 3) == (1, 2, 3)
```

Это позволяет указать имя файла в качестве атрибута блока кода и использовать CSS для визуализации атрибута в качестве заголовка.

---

Альтернативный подход - использование фильтра pandoc;Я обычно советую использовать Lua фильтры . Это также позволило бы включить файл напрямую, так что можно было бы просто написать

``` {.python filename="ch1/test_one.py"}
```

, а фильтр обработал бы включение содержимого. Это должно быть только несколько строк Lua.

Answer 2

У Markdown обычно нет возможности «включать» файлы или фрагменты файлов, хотя может существовать вариант Markdown, который может поддерживать эту возможность. Таким образом, выдержки обычно выполняются с помощью копирования + вставки.

Вы также должны будете указать имя файла самостоятельно. Markdown / Pandoc не знает имен файлов для фрагментов кода.

Отдельно у Markdown обычно нет возможности применять пользовательские стили. Для этого вам потребуется встроить HTML, а встроенный HTML может оказаться проблематичным для форматов вывода, отличных от HTML.

Рассматривали ли вы использование разметки Asciidoctor вместо Markdown? Это формат разметки, который похож, но более эффективен, чем Markdown. Файл разрешений Asciidoctor включает в себя файлы, выдержки из файлов и роли, определенные автором (что приводит к классам CSS). Вы можете создать собственное расширение include, которое будет включать имя выходного файла в вывод (или копировать + вставить).