roadmap/docs/features/OxHugo compatibility.md

tags
plugin/transformer

org-roam is a plain-text personal knowledge management system for emacs. ox-hugo is org exporter backend that exports org-mode files to Hugo compatible Markdown.

Because the Markdown generated by ox-hugo is not pure Markdown but Hugo specific, we need to transform it to fit into Quartz. This is done by Plugin.OxHugoFlavouredMarkdown. Even though this making plugins was written with ox-hugo in mind, it should work for any Hugo specific Markdown.

plugins: {
  transformers: [
    Plugin.FrontMatter({ delims: "+++", language: "toml" }), // if toml frontmatter
    // ...
    Plugin.OxHugoFlavouredMarkdown(),
    Plugin.GitHubFlavoredMarkdown(),
    // ...
  ],
},

Usage

Quartz by default doesn't understand org-roam files as they aren't Markdown. You're responsible for using an external tool like ox-hugo to export the org-roam files as Markdown content to Quartz and managing the static assets so that they're available in the final output.

Configuration

• Link resolution
  • wikilinks: Whether to replace {{ relref }} with Quartz wikilinks
  • removePredefinedAnchor: Whether to remove pre-defined anchor set by ox-hugo.
• Image handling
  • replaceFigureWithMdImg: Whether to replace <figure/> with ![]()
• Formatting
  • removeHugoShortcode: Whether to remove hugo shortcode syntax ({{}})

[!warning]

While you can use Plugin.OxHugoFlavoredMarkdown and Plugin.ObsidianFlavoredMarkdown together, it's not recommended because it might mutate the file in unexpected ways. Use with caution.