diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 29a49d3e8eac4c45644736bc3d8368ebe9e94900..ac0876ff3cd3c52db8967e6fecf78f70a49ef84a 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -6,6 +6,10 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi == Unreleased +=== Added + +* allow location of config file to be specified using `config_file` key in extension configuration (#48) + === Fixed * unconvert page titles from HTML to AsciiDoc to use in aggregate document (#41) diff --git a/docs/pdf-extension/modules/ROOT/pages/configure.adoc b/docs/pdf-extension/modules/ROOT/pages/configure.adoc index a565efb5ce0a8e9654003b7004652e7a02e2cf73..9550147a8fbd60a8301176fa1c5c6f443893f276 100644 --- a/docs/pdf-extension/modules/ROOT/pages/configure.adoc +++ b/docs/pdf-extension/modules/ROOT/pages/configure.adoc @@ -1,10 +1,10 @@ = Configure Your PDFs -:description: The Antora PDF extension uses its default configuration and any custom settings defined in antora-assembler.yml when it generates PDFs. +:description: The Antora PDF extension uses the extension configuration and any custom settings defined in antora-assembler.yml when it generates PDFs. -The Antora PDF extension uses its default configuration and any custom settings defined in the optional [.path]_antora-assembler.yml_ file when it generates PDFs. +The Antora PDF extension uses the extension configuration and any custom settings defined in the optional [.path]_antora-assembler.yml_ file when it generates PDFs. [#default] -== Default configuration +== Extension configuration When the PDF extension is xref:register.adoc[registered in your playbook or using the CLI], the extension will generate PDFs when you run Antora. The PDF extension builds PDF files from the content sources defined in your Antora playbook file ([.path]_antora-playbook.adoc_). @@ -20,6 +20,20 @@ This modification is done to work around duplicate content problems in the aggre The default settings for the PDF configuration keys are listed in the table on xref:configuration-keys.adoc[]. You can override the default configuration values and specify additional AsciiDoc attributes for your PDFs by creating a configuration file named [.path]_antora-assembler.yml_. +If you want to use a different Assembler configuration file, you can specify the location of the file using the `config_file` key on the extension configuration in the Antora playbook. +For example + +.antora-playbook.yml +[,yml] +---- +antora: + extensions: + - require: '@antora/pdf-extension' + config_file: './pdf-config.yml' +---- + +More than just giving you the option to customize the name of the configuration file, this key allows you to use <>. + NOTE: The value of the `revnumber` attribute of the assembled document defaults to the component version of the pages being assembled. NOTE: If [.path]_Gemfile.lock_ is adjacent to [.path]_antora-assembler.yml_, the PDF extension will use the command `bundle exec asciidoctor-pdf` by default, thus assuming gems are managed using Bundler (as we recommend). @@ -41,3 +55,26 @@ If the PDF extension doesn't locate [.path]_antora-assembler.yml_ in the playboo See xref:assembler-configuration-file.adoc[] to learn how to create this file and set key-value pairs in it to customize your PDFs. For an overview of all available PDF extension configuration keys, see xref:configuration-keys.adoc[]. + +[#multiple] +== Custom configuration per component group + +Normally, Assembler uses the same configuration (defined in [.path]_antora-assembler.yml_) for all component versions on which it runs. +However, it's possible to use different configurations for different component versions by registering the extension multiple times, each time with a different configuration file. +For example: + +[,yml] +---- +antora: + extensions: + - require: '@antora/pdf-extension' + config_file: antora-assembler-a.yml + - require: '@antora/pdf-extension' + config_file: antora-assembler-b.yml +---- + +Each configuration file should specify a component version filter using the `component_version` key. +The component versions that these filters match should not overlap. + +WARNING: In order to prevent Antora from cleaning the build directory between instances of the extension, set the `clean` key to `false` for all but the last entry. +Alternately, you can specify a different build directory per configuration. diff --git a/packages/pdf-extension/lib/index.js b/packages/pdf-extension/lib/index.js index d152e4b00f88eb9f62c7661a509df2a1219f2b40..a121f0ea2181c33627d96c598a059d6eb58c7478 100644 --- a/packages/pdf-extension/lib/index.js +++ b/packages/pdf-extension/lib/index.js @@ -2,7 +2,7 @@ const convertDocumentToPdf = require('./convert-document-to-pdf') -module.exports.register = function () { +module.exports.register = function ({ config: { configFile: configSource } }) { this.once('beforeProcess', ({ siteAsciiDocConfig }) => { siteAsciiDocConfig.keepSource = true }) @@ -14,6 +14,6 @@ module.exports.register = function () { return require('@antora/assembler') // when installed separate from Antora, perhaps in project } })() - return assembleContent.call(this, playbook, contentCatalog, convertDocumentToPdf, { siteCatalog }) + return assembleContent.call(this, playbook, contentCatalog, convertDocumentToPdf, { configSource, siteCatalog }) }) } diff --git a/packages/pdf-extension/test/pdf-extension-test.js b/packages/pdf-extension/test/pdf-extension-test.js index 7df4bd92d7af896d3c910374f98c4fdbd7157b5a..3beabac87492209ca97881f436480e61161cc2b9 100644 --- a/packages/pdf-extension/test/pdf-extension-test.js +++ b/packages/pdf-extension/test/pdf-extension-test.js @@ -10,11 +10,14 @@ describe('pdf-extension', () => { once (eventName, fn) { this[eventName] = fn }, + require, }) - let generatorContext + let generatorContext, registerVars + beforeEach(() => { generatorContext = createGeneratorContext() + registerVars = { config: {} } }) describe('bootstrap', () => { @@ -24,15 +27,51 @@ describe('pdf-extension', () => { }) it('should set keepSource on AsciiDoc config during beforeProcess event', () => { - ext.register.call(generatorContext) + ext.register.call(generatorContext, registerVars) const siteAsciiDocConfig = {} generatorContext.beforeProcess({ siteAsciiDocConfig }) expect(siteAsciiDocConfig.keepSource).to.be.true() }) it('should be able to call register function exported by extension', () => { - ext.register.call(generatorContext) + ext.register.call(generatorContext, registerVars) expect(generatorContext.navigationBuilt).to.be.instanceOf(Function) }) + + it('should call assembleContent function when navigationBuilt event is emitted', () => { + ext.register.call(generatorContext, registerVars) + const required = [] + let assembleContentArguments + generatorContext.require = function (id) { + required.push(id) + return { + assembleContent () { + assembleContentArguments = arguments + }, + } + } + generatorContext.navigationBuilt({}) + expect(required).to.have.lengthOf(1) + expect(required[0]).to.equal('@antora/assembler') + expect(assembleContentArguments[2]).to.be.instanceOf(Function) + expect(assembleContentArguments[3]).to.be.instanceOf(Object) + expect(assembleContentArguments[3].configSource).to.be.undefined() + }) + + it('should allow configFile to be overridden by extension configuration', () => { + registerVars.config.configFile = './pdf-config.yml' + ext.register.call(generatorContext, registerVars) + let assembleContentArguments + generatorContext.require = function () { + return { + assembleContent () { + assembleContentArguments = arguments + }, + } + } + generatorContext.navigationBuilt({}) + expect(assembleContentArguments[3]).to.be.instanceOf(Object) + expect(assembleContentArguments[3].configSource).to.equal('./pdf-config.yml') + }) }) })