Org-mode. Экспорт в Hugo

Обновлено 2023-08-13 9 мин. для прочтения Computer-Science

Экспорт org-mode в Hugo является одной из составных частей научного рабочего процесса на основе Emacs и org-mode.

Содержание

1 Использование языка Markdown внутри Org

  • При экспорте Org преобразуется в стандартный Markdown. Однако в Hugo используются собственные нестандартные расширения (см. Синтаксис Markdown для генератора сайтов Hugo).
  • При необходимости их можно вставлять прямо в текст.

2 Соответствие языков разметки

Таблица 1: Соответствие разметок org и markdown
OrgMarkdownПосле рендеринга
*bold***bold**bold
/italics/_italics_italics
=monospace=`monospace`monospace
~key-binding~`key-binding` 1key-binding
~key-binding~<kbd>key-binding</kbd> 2
+strike-through+~~strike-through~~strike-through
_underline_<span class = "underline">underline</span> 3underline

3 Настройка экспорта

  • Экспорт производится в рамках общего фреймворка org-mode для экспорта (см. Org-mode. Экспорт).

3.1 Экспорт специфических элементов

3.1.1 Экспорт операторов Hugo

  • Для экспорта конкретных элементов, необходимых только для Hugo, следует использовать блок export. Например, оглавление задаётся следующим образом:
    #+begin_export hugo
{{</* toc */>}}
#+end_export
  • Это позволяет задавать оглавление только для Hugo.

3.1.2 Отбивка резюме (Summary Splitter)

  • Отбивка резюме задаётся конструкцией
    #+hugo: more

3.1.3 Резюме и подробная информация

  • Специальный блок «Детали» #+begin_details … #+end_details используется для создания элемента, раскрывающего дополнительные сведения (<details> и <summary>).

    #+begin_details
#+begin_summary
Краткая информация
#+end_summary
А здесь подробная информация.
#+end_details

  • Выглядить это так:

    Краткая информация

    А здесь подробная информация.

  • Если блок summary отсутствует, резюме будет заменено на некоторое значение по умолчанию. Так, блок

    #+begin_details
А здесь подробная информация.
#+end_details

    будет иметь следующий вид:

    А здесь подробная информация.

  • Можно показывать блок открытым по умолчанию. Для этого следует добавить атрибут HTML #+attr_html: :open t:

    #+attr_html: :open t
#+begin_details
#+begin_summary
Краткая информация
#+end_summary
А здесь подробная информация.
#+end_details
    Краткая информация

    А здесь подробная информация.

3.2 Свойства экспорта

3.2.1 Обязательные свойства

  • Для экспорта необходимо установить следующие обязательные свойства:
    • HUGO_SECTION - название раздела Hugo по умолчанию для всех сообщений. Обычно это свойство устанавливается для сообщений или блога. Значение по умолчанию устанавливается с помощью org-hugo-default-section-directory.
    • HUGO_BASE_DIR - корневой каталог сайта Hugo. Например, если HUGO_BASE_DIR установлен на ~/hugo/, то экспортированные файлы Markdown будут сохранены в каталог ~/hugo/content/<HUGO_SECTION>/.
  • Данные свойства можно устанавливать как на уровне файла, так и на уровне каталога или проекта.
  • Переменные на уровне каталога задаются в файле .dir-locals.el:
    ((org-mode . ((org-hugo-base-dir . "~/work/blog/git")
         (org-hugo-section . "ru/post"))))

3.2.2 Формат заголовка

  • Поддерживаются форматы заголовка TOML (по умолчанию) и YAML.

  1. Экспорт для всего файла

    #+hugo_front_matter_format: yaml

  1. Экспорт для поддерева

    :PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:

3.2.3 Свойства экспорта для заголовка Hugo

Таблица 2: Сводная таблица свойств экспорта для заголовка Hugo
Hugo front-matter (TOML)Уровень файлаУровень поддерева
title = "foo"#+title: foo* foo
date = 2017-09-11T14:32:00-04:00CLOSED: [2017-09-11 Mon 14:32]
date = 2017-07-24#+date: 2017-07-24:EXPORT_DATE: 2017-07-24
publishDate = 2018-01-26#+hugo_publishdate: 2018-01-26SCHEDULED: <2018-01-26 Fri>
publishDate = 2018-01-26:EXPORT_HUGO_PUBLISHDATE: 2018-01-26:
expiryDate = 2999-01-01#+hugo_expirydate: 2999-01-01DEADLINE: <2999-01-01 Tue>
expiryDate = 2999-01-01:EXPORT_HUGO_EXPIRYDATE: 2999-01-01:
lastmod = <current date>#+hugo_auto_set_lastmod: t:EXPORT_HUGO_AUTO_SET_LASTMOD: t
lastmod = <current date>#+hugo_auto_set_lastmod: t
tags = ["toto", "zulu"]#+hugo_tags: toto zulu* foo :toto:zulu:
categories = ["x", "y"]#+hugo_categories: x y* foo :@x:@y:
draft = true#+hugo_draft: true* TODO foo
draft = false#+hugo_draft: false* foo или * DONE foo
weight = 123 (manual)#+hugo_weight: 123:EXPORT_HUGO_WEIGHT: 123
weight = 123 (auto-calc):EXPORT_HUGO_WEIGHT: auto
tags_weight = 123 (manual)#+hugo_weight: :tags 123:EXPORT_HUGO_WEIGHT: :tags 123
tags_weight = 123 (auto-calc):EXPORT_HUGO_WEIGHT: :tags auto
weight = 123 (in [menu.foo])#+hugo_menu: :menu foo :weight 123:EXPORT_HUGO_MENU: :menu foo
categories_weight = 123#+hugo_weight: :categories 123

3.3 Особенности экспорта

4 Сочетания клавиш

  • Экспорт осуществляется через стандартный интерфейс экспорта в org-mode.

4.1 Для режимов один пост на файл и один пост на поддерево

  • C-c C-e H H Экспорт «Что я имею в виду».
    • Если курсор находится в допустимом поддереве сообщения Hugo, экспортирует это поддерево в сообщение Hugo в Markdown. Допустимое поддерево сообщений Hugo - это поддерево, для которого установлено свойство EXPORT_FILE_NAME.
    • Если файл предназначен для экспорта целиком (т.е. имеет ключевое слово #+title), экспортирует весь файл Org в сообщение Hugo в Markdown.
  • C-c C-e H A Экспорт всего «Что я имею в виду».
    • Если в org-файле есть одно или несколько действительных поддеревьев сообщений Hugo, экспортирует их в сообщения Hugo в Markdown.
    • Если файл предназначен для экспорта целиком (т. е. вообще нет действительных поддеревьев сообщений Hugo и есть ключевое слово #+title), экспортирует весь org-файл в сообщение Hugo в Markdown.

4.2 Для режима один пост на файл

  • C-c C-e H h Экспорт файла Org в сообщение Hugo в Markdown.

5 Теги и категории

5.1 Экспорт уровня файла

  • Список тегов:
    #+hugo_tags
  • Список категорий:
    #+hugo_categories

5.2 Экспорт уровня поддерева

5.2.1 Теги

Экспортируемые теги Hugo задаются как теги org-mode:

* My post                                                         :tag1:tag2:

5.2.2 Категории

Экспортируемые категорий Hugo задаются как теги org-mode, для которых установлен префикс @:

* My post                                                       :@cat1:@cat2:

5.2.3 Использование filetags

Для экспорта на уровне поддерева можно использовать оператор

#+filetags

Например:

#+filetags: :@cat1:tag1:tag2:

5.3 Дефисы и пробелы в тегах

В тегах org-mode нельзя использовать дефисы и пробелы. Конвертер использует следующие настройки:

  • одиночное подчёркивание переводится в дефис (конфигурационная переменная org-hugo-prefer-hyphen-in-tags);
  • двойное подчёркивание переводится в пробел (конфигурационная переменная org-hugo-allow-spaces-in-tags).

6 Дополнительные поля

Нестандартные дополнительные поля в основном используются для установки пользовательских параметров оформления.

  • Чтобы установить настраиваемый параметр предварительной записи в поддереве, используется свойство :EXPORT_HUGO_CUSTOM_FRONT_MATTER:.
  • Чтобы задать настраиваемый параметр внешнего вида глобально или для потока экспорта для каждого файла, используется ключевое слово #+HUGO_CUSTOM_FRONT_MATTER:.

6.1 Синтаксис

6.1.1 Пары ключ-значение

  • Можно записывать в одном поле:
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1 :key2 value2
:END:
  • Можно разбить на несколько полей:
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :key2 value2
:END:
  • На уровне файла посредством ключевого слова:
    #+hugo_custom_front_matter: :key1 value1
#+hugo_custom_front_matter: :key2 value2
  • Например, запись
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :feature true
:END:
    примет вид (для TOML)
    feature = true

6.1.2 Списочные значения

  • Запись имеет следующий вид:
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 '(elem11 elem12) :key2 '(elem21 elem22)
:END:
  • Например, запись
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :animals '(dog cat "penguin" "mountain gorilla")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :integers '(123 -5 17 1_234)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :floats '(12.3 -5.0 -17E-6)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :booleans '(true false)
:END:
    примет вид (для TOML)
    animals = ["dog", "cat", "penguin", "mountain gorilla"]
integers = [123, -5, 17, 1_234]
floats = [12.3, -5.0, -1.7e-05]
booleans = [true, false]

6.1.3 Многоуровневые значения

  • Запись имеет следующий вид:
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 '((subkey11 . subval11) (subkey12 . (subelem121 subelem122))) :key2 '((subkey21 . subval21))
:END:
  • Например, запись
    :PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :versions '((emacs . "27.0.50") (hugo . "0.48"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header '((image . "projects/Readingabook.jpg") (caption . "stay hungry, stay foolish"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :collection '((animals . (dog cat "penguin" "mountain gorilla")) (integers . (123 -5 17 1_234)) (floats . (12.3 -5.0 -17E-6)) (booleans . (true false)))
:END:
    примет вид (для TOML)
    [versions]
  emacs = "27.0.50"
  hugo = 0.48
[header]
  image = "projects/Readingabook.jpg"
  caption = "stay hungry, stay foolish"
[collection]
  animals = ["dog", "cat", "penguin", "mountain gorilla"]
  integers = [123, -5, 17, 1_234]
  floats = [12.3, -5.0, -1.7e-05]
  booleans = [true, false]

6.1.4 Прямая вставка преамбул

Можно описать преамбулу непосредственно (если невозможно сгенерить средствами экспорта). Для этого используется аргумент заголовка блока кода :front_matter_extra t.

  1. Преамбула TOML

    По умолчанию используется преамбула в формате TOML, поэтому нет необходимости устанавливать ключевое слово :EXPORT_HUGO_FRONT_MATTER_FORMAT: toml.

    * Post with TOML front-matter (default)
:PROPERTIES:
:EXPORT_FILE_NAME: extra-front-matter-toml
:END:
The contents of the ~#+begin_src toml :front_matter_extra t~ TOML
block here will get appended to the TOML front-matter.
#+begin_src toml :front_matter_extra t
[[foo]]
  bar = 1
  zoo = "abc"
[[foo]]
  bar = 2
  zoo = "def"
#+end_src

  1. Преамбула YAML

    * Post with YAML front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: extra-front-matter-yaml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
The contents of the ~#+begin_src yaml :front_matter_extra t~ YAML
block here will get appended to the YAML front-matter.
#+begin_src yaml :front_matter_extra t
foo:
  - bar: 1
    zoo: abc
  - bar: 2
    zoo: def
#+end_src

7 Экспорт элементов

  • При экспорте элементов для Hugo используется блок
    #+begin_export hugo
Текст для Hugo
#+end_export
  • Возникла коллизия, когда из единого источника необходимо было вывести информацию и в Hugo, и в Markdown. При экспорте посредством блока
    #+begin_export markdown
Текст для Markdown
#+end_export
    этот текст появлялся и в файле для Hugo. Для обхода этой ситуации я стал задавать блок для Markdown в следующем виде:
    #+begin_src markdown :exports (if (eq org-export-current-backend 'md) "" "none")
Текст для Markdown
#+end_src

8 Пакет страниц (page bundle)

8.1 Общая информация

  • Для экспорта в пакет (папку) страниц нужно установить для свойства :EXPORT_HUGO_BUNDLE: (или =#+HUGO_BUNDLE) имя каталога в качестве значения.
  • Значение :EXPORT_FILE_NAME: или #+EXPORT_FILE_NAME устанавливается в зависимости от вида пакетов страниц.
  • Пакеты страниц (Hugo Page Bundle) бывают двух видов:
    • пакет-страница (Leaf Bundle)
      • нет подстраниц,
      • контент и вложения для отдельных страниц,
      • индексный файл: index.md,
      • пример: content/posts/my-post/index.md,
      • :EXPORT_FILE_NAME: index,
      • #+EXPORT_FILE_NAME: index.
    • пакет веток (Branch Bundle)
      • содержит подстраницы,
      • контент и вложения для страниц раздела (домашняя страница, раздел, термины таксономии, список таксономии),
      • индексный файл: _index.md,
      • пример: content/posts/_index.md,
      • :EXPORT_FILE_NAME: _index,
      • #+EXPORT_FILE_NAME: _index.
    • Пример пакет-страницы (Leaf Bundle):
      • экспорт в content/xyz/index.md
        ​* Page title
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: xyz
:EXPORT_FILE_NAME: index
:END:
Content
    • Пример пакета веток (Branch Bundle)
      • экспорт в content/uvw/_index.md
        ​* Page title
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: uvw
:EXPORT_FILE_NAME: _index
:END:
Content

8.2 Читаемые курсы

Чтобы сделать список и содержание читаемых курсов (или какой-либо документации).

  • Пусть курс называется mathsec.
  • Свойства для экспорта:
    :PROPERTIES:
:EXPORT_HUGO_SECTION: ru/course
:EXPORT_HUGO_BUNDLE: mathsec
:EXPORT_FILE_NAME: _index
:END:

9 Автоматический экспорт при сохранении

9.1 Установка на уровне каталога

  • Установка делается в файле .dir-locals.el в текущем каталоге:
    ((org-mode . ((eval . (org-hugo-auto-export-mode)))))
  • Конфигурация применяется ко всем org-файлам в каталоге.

9.2 Установка на уровне проекта

  • Если org-файлы находятся в некотором каталоге, например в content-org, то в файле .dir-locals.el задаётся конфигурация для этого каталога:
    (("content-org/"
  . ((org-mode . ((eval . (org-hugo-auto-export-mode)))))))

9.3 Установка для конкретного файла

  • Для каждого файла можно задать локальные переменные:
    ​* COMMENT Local Variables                          :ARCHIVE:
# Local Variables:
# eval: (org-hugo-auto-export-mode)
# End:
  • Рекомендуется добавить заголовок Footnotes перед заголовком Local Variables, чтобы в случае добавления каких-либо сносок они добавлялись в данный раздел.
  • В противном случае будет автоматически создан новый заголовок Footnotes в конце файла, и заголовок Local Variables больше не будет последним и не будет обрабатываться.
  • Перечитать локальные переменные можно командой:
    M-x normal-mode

9.4 Запрет авто сохранения для конкретного файла

  • Для каждого файла можно задать локальные переменные для запрета экспорта:
    ​* COMMENT Local Variables                          :ARCHIVE:
# Local Variables:
# eval: (org-hugo-auto-export-mode -1)
# End:

10 Цитирование

10.1 Формат цитирования pandoc

  • Исторический формат цитирования.
  • Рекомендуется перейти на формат цитирования org-cite.

10.2 Формат цитирования org-cite

  • Цитирование основано на org-cite (см. Emacs. Работа с библиографией. Org-cite).
  • Рекомендуется использовать процессор экспорта csl.
  • При задании ключевого слова #+print_bibliography: по умолчанию создаётся секция References.
  • Можно задать другое название для этой секции:
    (with-eval-after-load 'ox-hugo
  (plist-put org-hugo-citations-plist :bibliography-section-heading "Bibliography"))
  • Если для этого свойства задана пустая строка, этот заголовок не будет вставлен автоматически 4:
    (with-eval-after-load 'ox-hugo
  (plist-put org-hugo-citations-plist :bibliography-section-heading ""))

  1. Если org-hugo-use-code-for-kbd равно nil (по умолчанию). ↩︎

  2. Если org-hugo-use-code-for-kbd не равно nil. Требует настроек CSS для интерпретации тега <kbd>. ↩︎

  3. Требует настроек CSS для интерпретации тега <underline>. ↩︎

  4. Так должно быть, но не работает. Вообще литература не печатается. ↩︎

Links to this note

Hugo Org-Mode Emacs
Дмитрий Сергеевич Кулябов
Дмитрий Сергеевич Кулябов
Профессор кафедры теории вероятностей и кибербезопасности

Мои научные интересы включают физику, администрирование Unix и сетей.

Похожие