From 860318abc7d70d9abb17f0e1b7d4cdbfa9e49175 Mon Sep 17 00:00:00 2001 From: Alexander Schwartz Date: Fri, 20 Dec 2024 00:44:46 +0100 Subject: [PATCH] Update docs and templates to recommend an absolute path for the `pdf-themesdir` (#1750) --- CHANGELOG.adoc | 2 +- doc/users-guide/modules/ROOT/pages/faq.adoc | 19 +++++++++++++++++++ .../advanced/pdf-non-latin-languages.adoc | 2 +- src/main/resources/AsciiDocBundle.properties | 2 ++ .../liveTemplates/AsciiDocLiveTemplates.xml | 2 +- 5 files changed, 24 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index a0c92e5f3..3a80bb51f 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -9,7 +9,7 @@ This document provides a high-level view of the changes introduced by release. === 0.43.5 -... +- Update docs and templates to recommend an absolute path for the `pdf-themesdir` (#1750) === 0.43.4 diff --git a/doc/users-guide/modules/ROOT/pages/faq.adoc b/doc/users-guide/modules/ROOT/pages/faq.adoc index 2e9ff8022..4db8574c1 100644 --- a/doc/users-guide/modules/ROOT/pages/faq.adoc +++ b/doc/users-guide/modules/ROOT/pages/faq.adoc @@ -114,6 +114,25 @@ This is not supported by Asciidoctor PDF. See xref:faq/diagrams-in-pdf-without-text.adoc[] for more details. +=== Themes are not used when creating a PDF via the IDE + +To use a theme when creating PDFs in the IDE, always specify an absolute directory pointing to the `themes` folder. + +When specifying the folder in a regular AsciiDoc file, use the `{docdir}` attribute as a prefix to point to a folder +relative to the current document: + +[source,asciidoc] +---- +:pdf-themesdir: {docdir}/themes +---- + +When specifying a theme relative in an `.asciidoctorconfig` file, use the folder of that file by prefixing `{asciidoctorconfigdir}`: + +[source,asciidoc] +---- +:pdf-themesdir: {asciidoctorconfigdir}/themes +---- + == Other Troubles === Something is not working as I expect it to work, where can I get help? diff --git a/doc/users-guide/modules/ROOT/pages/features/advanced/pdf-non-latin-languages.adoc b/doc/users-guide/modules/ROOT/pages/features/advanced/pdf-non-latin-languages.adoc index 45c351f6c..839992db2 100644 --- a/doc/users-guide/modules/ROOT/pages/features/advanced/pdf-non-latin-languages.adoc +++ b/doc/users-guide/modules/ROOT/pages/features/advanced/pdf-non-latin-languages.adoc @@ -19,7 +19,7 @@ A complete example is available in https://github.com/ahus1/asciidoctor-deepdive [source,text] ---- = 标题 -:pdf-themesdir: themes <1> +:pdf-themesdir: {docdir}/themes <1> :pdf-theme: zh_CN <2> :pdf-fontsdir: fonts <3> diff --git a/src/main/resources/AsciiDocBundle.properties b/src/main/resources/AsciiDocBundle.properties index 4cae6e767..6d3da908d 100644 --- a/src/main/resources/AsciiDocBundle.properties +++ b/src/main/resources/AsciiDocBundle.properties @@ -644,10 +644,12 @@ asciidoc.attributes.builtin.pdf-style.default-value=not set asciidoc.attributes.builtin.pdf-style.values=any asciidoc.attributes.builtin.pdf-themesdir.text=The directory where the theme file is located. Specifying an absolute path is recommended.\n\ +Prefix with {docdir} to ensure a path relative to the current document\n\ If you use images in your theme, image paths are resolved relative to this directory. If :pdf-theme: ends with .yml, and :pdf-themesdir: is not specified, then :pdf-themesdir: defaults to the directory of the path specified by :pdf-theme:. asciidoc.attributes.builtin.pdf-themesdir.default-value=not set asciidoc.attributes.builtin.pdf-themesdir.values=any asciidoc.attributes.builtin.pdf-stylesdir.text=The directory where the theme file is located. Specifying an absolute path is recommended.\n\ +Prefix with {docdir} to ensure a path relative to the current document\n\ If you use images in your theme, image paths are resolved relative to this directory. If :pdf-theme: ends with .yml, and :pdf-themesdir: is not specified, then :pdf-themesdir: defaults to the directory of the path specified by :pdf-theme:. asciidoc.attributes.builtin.pdf-stylesdir.default-value=not set asciidoc.attributes.builtin.pdf-stylesdir.values=any diff --git a/src/main/resources/liveTemplates/AsciiDocLiveTemplates.xml b/src/main/resources/liveTemplates/AsciiDocLiveTemplates.xml index 27afa1435..a6654d7c3 100644 --- a/src/main/resources/liveTemplates/AsciiDocLiveTemplates.xml +++ b/src/main/resources/liveTemplates/AsciiDocLiveTemplates.xml @@ -304,7 +304,7 @@