j/cyberware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
cyberware/docs/features/OxHugo compatibility.md
Hrishikesh Barman 2f99339dcf
feat: add transformations for latex in oxhugofm (#510) 
ox-hugo currently supports the following syntax for latex equations:
- https://orgmode.org/manual/LaTeX-fragments.html
- https://ox-hugo.scripter.co/doc/equations

This syntax is supported by mathjax as is mentioned in the ox-hugo documentation.

But quartz uses remark-math which has some issues with the \( \) syntax.
See https://github.com/remarkjs/remark-math/issues/39

This change adds few more transformations to the OxHugoFlavouredMarkdown
plugin, which makes a best effort conversion of this syntax into what
the Quartz Latex transformer plugin supports.

With these changes, the generated files show latex formatting with
default quartz configuration.

Sidenote on `\_` escape by ox-hugo:

ox-hugo escapes, _ using \_, we match against it after we transform
equations into what quartz supports($$ and $).

This could be achieved using lookaround like regex as follows
```js
(?<=(\$|\$\$)[\s\S]*) -> Positive lookbehind for $ or $$
\\_ -> Matches \_
(?=[\s\S]*(?:\1)) Positive lookahead for $ or $$ if matched
const escapedUnderscoreRegex = new RegExp(/(?<=(\$|\$\$)[\s\S]*)\\_(?=[\s\S]*(?:\1))/, "g")
````

But since lookahead/behind can slow things down on large files, we just
look up all equations with $ and $$ delimiters and then try replacing \_
2023-09-29 11:35:26 -07:00

1.9 KiB
Raw Blame History

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
  • Image handling
    • replaceFigureWithMdImg: Whether to replace <figure/> with ![]()
  • Formatting
    • removeHugoShortcode: Whether to remove hugo shortcode syntax ({{}})
    • replaceOrgLatex: Whether to replace org-mode formatting for latex fragments with what Plugin.Latex supports.

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.