Adding a Custom XML Output Format in Hugo

Joshua T. Rowe included in devops-manual

2022-05-19 340 words 2 minutes

Contents

Problem

tl;dr : I want to integrate blog posts in Hugo into a DevOps-Manual that I use as a reference document for programming and system administration activities. The DevOps-Manual is assembled using DocBook.

Approach

Create a new output format for Hugo specifically to produce the DocBook XML that I want. Then I can include that output into other DocBook documents.

Solution - Failed : Generate Via Hugo

Add New Output Format To Config

Call the output format DevOps-Manual. Add the following snippets into the config.toml.

The DevOps-Manual output will be written to public/devops-manual/.

[outputs]
  page = [ "DevOps-Manual", ... ]

[outputFormats.DevOps-Manual]
  mediaType = "application/xml+docbook"
  isPlainText = true
  isHTML = false
  noUgly = false
  path = 'devops-manual'

[mediaTypes]
  [mediaTypes."application/xml+docbook"]
    suffixes = [ "xml" ]

As expected, complains about having no layout for “devops-manual” for kind “page”.

$ hugo
WARN 2022/05/19 11:21:33 found no layout file for "devops-manual" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

Add New Layout

This layout will produce a DocBook document.

It will expect the content of the page to be included via a file named content.xml.

As an example, the post content/posts/2022/04/11.105912.md produces a file public/devops-manual/2022/04/11/11.105912/index.xml and expects the content of the page to be found in file public/devops-manual/2022/04/11/11.105912/content.xml.

<section>
  <title>{{- .Title -}}</title>

  <info>
    {{- with .Params.tags -}}
      {{ range . }}
      <keyword>{{ . }}</keyword>
      {{- end -}}
    {{- end }}
  </info>

  {{- with .Params.tags -}}
    {{ range . }}
    <indexterm><primary>{{ . }}</primary></indexterm>
    {{- end -}}
  {{- end }}

  <!-- file : {{ .File }} -->

  <xi:include href="content.xml" />

</section>

Conclusion

Hugo can produce HTML content easily and can produce the metadata in any format easily. But I need to produce the content into a new format. That appears beyond the scope of Hugo.

I experimented with trying to make an exec call in the templates or using a short code or just calling pandoc externally to convert from markdown to docbook.

In the end, I think I would need to put a lot of transformation logic into this repo.

I would rather have the DevOps-Manual project be able to read Hugo files and keep the transformation logic in that repo.