Some inline math: \(a^2 + b^2 = c^2\)
+``` +You will have to [add MathJax](https://www.mathjax.org/#gettingstarted) to your template to properly render the math. + +For **Pandoc >= 2.11**, you can use [citations](https://pandoc.org/MANUAL.html#extension-citations). +One way is to employ [BibTeX files](https://en.wikibooks.org/wiki/LaTeX/Bibliography_Management#BibTeX) to cite: + +``` +--- +title: Citation document +--- +--- +bibliography: assets/bibliography.bib +... +This is a citation: @Doe2022 +``` + +Note that Hugo will **not** pass its metadata YAML block to Pandoc; however, it will pass the **second** meta data block, denoted with `---` and `...` to Pandoc. +Thus, all Pandoc settings should go there. + +You can also add all elements from a bibliography file (without citing them explicitly) using: + +``` +--- +title: My Publications +--- +--- +bibliography: assets/bibliography.bib +nocite: | + @* +... +``` + +It is also possible to provide a custom [CSL style](https://citationstyles.org/authors/) by passing `csl: path-to-style.csl` as a Pandoc option. + + ## Learn Markdown Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: diff --git a/markup/pandoc/convert.go b/markup/pandoc/convert.go index ae90cf41770..228a1b3a7aa 100644 --- a/markup/pandoc/convert.go +++ b/markup/pandoc/convert.go @@ -15,12 +15,17 @@ package pandoc import ( + "bytes" + "fmt" + "strconv" + "strings" + "sync" + "github.com/gohugoio/hugo/common/hexec" "github.com/gohugoio/hugo/htesting" "github.com/gohugoio/hugo/identity" - "github.com/gohugoio/hugo/markup/internal" - "github.com/gohugoio/hugo/markup/converter" + "github.com/gohugoio/hugo/markup/internal" ) // Provider is the package entry point. @@ -65,6 +70,9 @@ func (c *pandocConverter) getPandocContent(src []byte, ctx converter.DocumentCon return src, nil } args := []string{"--mathjax"} + if supportsCitations(c.cfg) { + args = append(args[:], "--citeproc") + } return internal.ExternallyRenderContent(c.cfg, ctx, src, binaryName, args) } @@ -77,6 +85,72 @@ func getPandocBinaryName() string { return "" } +type pandocVersion struct { + major, minor int64 +} + +func (left pandocVersion) greaterThanOrEqual(right pandocVersion) bool { + return left.major > right.major || (left.major == right.major && left.minor >= right.minor) +} + +var versionOnce sync.Once +var foundPandocVersion pandocVersion + +// getPandocVersion parses the pandoc version output +func getPandocVersion(cfg converter.ProviderConfig) (pandocVersion, error) { + var err error + + versionOnce.Do(func() { + argsv := []any{"--version"} + + var out bytes.Buffer + argsv = append(argsv, hexec.WithStdout(&out)) + + cmd, err := cfg.Exec.New(pandocBinary, argsv...) + if err != nil { + cfg.Logger.Errorf("Could not call pandoc: %v", err) + foundPandocVersion = pandocVersion{0, 0} + return + } + + err = cmd.Run() + if err != nil { + cfg.Logger.Errorf("%s --version: %v", pandocBinary, err) + foundPandocVersion = pandocVersion{0, 0} + return + } + + outbytes := bytes.Replace(out.Bytes(), []byte("\r"), []byte(""), -1) + output := strings.Split(string(outbytes), "\n")[0] + // Split, e.g., "pandoc 2.5" into 2 and 5 and convert them to integers + versionStrings := strings.Split(strings.Split(output, " ")[1], ".") + majorVersion, err := strconv.ParseInt(versionStrings[0], 10, 64) + if err != nil { + println(err) + } + minorVersion, err := strconv.ParseInt(versionStrings[1], 10, 64) + if err != nil { + println(err) + } + foundPandocVersion = pandocVersion{majorVersion, minorVersion} + }) + + return foundPandocVersion, err +} + +// SupportsCitations returns true for pandoc versions >= 2.11, which include citeproc +func supportsCitations(cfg converter.ProviderConfig) bool { + foundPandocVersion, err := getPandocVersion(cfg) + supportsCitations := foundPandocVersion.greaterThanOrEqual(pandocVersion{2, 11}) && err == nil + if htesting.SupportsAll() { + if !supportsCitations { + panic(fmt.Sprintf("pandoc %d.%d does not support citations", foundPandocVersion.major, foundPandocVersion.minor)) + } + return true + } + return supportsCitations +} + // Supports returns whether Pandoc is installed on this computer. func Supports() bool { hasBin := getPandocBinaryName() != "" diff --git a/markup/pandoc/convert_test.go b/markup/pandoc/convert_test.go index f549d5f4ff8..aa362552091 100644 --- a/markup/pandoc/convert_test.go +++ b/markup/pandoc/convert_test.go @@ -25,18 +25,152 @@ import ( qt "github.com/frankban/quicktest" ) -func TestConvert(t *testing.T) { +func setupTestConverter(t *testing.T) (*qt.C, converter.Converter, converter.ProviderConfig) { if !Supports() { t.Skip("pandoc not installed") } c := qt.New(t) sc := security.DefaultConfig sc.Exec.Allow = security.NewWhitelist("pandoc") - p, err := Provider.New(converter.ProviderConfig{Exec: hexec.New(sc), Logger: loggers.NewErrorLogger()}) + cfg := converter.ProviderConfig{Exec: hexec.New(sc), Logger: loggers.NewErrorLogger()} + p, err := Provider.New(cfg) c.Assert(err, qt.IsNil) conv, err := p.New(converter.DocumentContext{}) c.Assert(err, qt.IsNil) - b, err := conv.Convert(converter.RenderContext{Src: []byte("testContent")}) + return c, conv, cfg +} + +func TestConvert(t *testing.T) { + c, conv, _ := setupTestConverter(t) + output, err := conv.Convert(converter.RenderContext{Src: []byte("testContent")}) + c.Assert(err, qt.IsNil) + c.Assert(string(output.Bytes()), qt.Equals, "testContent
\n") +} + +func runCiteprocTest(t *testing.T, content string, expected string) { + c, conv, cfg := setupTestConverter(t) + if !supportsCitations(cfg) { + t.Skip("pandoc does not support citations") + } + output, err := conv.Convert(converter.RenderContext{Src: []byte(content)}) c.Assert(err, qt.IsNil) - c.Assert(string(b.Bytes()), qt.Equals, "testContent
\n") + c.Assert(string(output.Bytes()), qt.Equals, expected) +} + +func TestGetPandocVersionCallTwice(t *testing.T) { + c, _, cfg := setupTestConverter(t) + + version1, err1 := getPandocVersion(cfg) + version2, err2 := getPandocVersion(cfg) + c.Assert(version1, qt.Equals, version2) + c.Assert(err1, qt.IsNil) + c.Assert(err2, qt.IsNil) +} + +func TestPandocVersionEquality(t *testing.T) { + c := qt.New(t) + v1 := pandocVersion{1, 0} + v2 := pandocVersion{2, 0} + v3 := pandocVersion{2, 2} + v4 := pandocVersion{1, 2} + v5 := pandocVersion{2, 11} + + // 1 >= 1 -> true + c.Assert(v1.greaterThanOrEqual(v1), qt.IsTrue) + + // 1 >= 2 -> false, 2 >= 1 -> tru + c.Assert(v1.greaterThanOrEqual(v2), qt.IsFalse) + c.Assert(v2.greaterThanOrEqual(v1), qt.IsTrue) + + // 2.0 >= 2.2 -> false, 2.2 >= 2.0 -> true + c.Assert(v2.greaterThanOrEqual(v3), qt.IsFalse) + c.Assert(v3.greaterThanOrEqual(v2), qt.IsTrue) + + // 2.2 >= 1.2 -> true, 1.2 >= 2.2 -> false + c.Assert(v3.greaterThanOrEqual(v4), qt.IsTrue) + c.Assert(v4.greaterThanOrEqual(v3), qt.IsFalse) + + // 2.11 >= 2.2 -> true, 2.2 >= 2.11 -> false + c.Assert(v5.greaterThanOrEqual(v3), qt.IsTrue) + c.Assert(v3.greaterThanOrEqual(v5), qt.IsFalse) +} + +func TestCiteprocWithHugoMeta(t *testing.T) { + content := ` +--- +title: Test +published: 2022-05-30 +--- +testContent +` + expected := "testContent
\n" + runCiteprocTest(t, content, expected) +} + +func TestCiteprocWithPandocMeta(t *testing.T) { + content := ` +--- +--- +--- +... +testContent +` + expected := "testContent
\n" + runCiteprocTest(t, content, expected) +} + +func TestCiteprocWithBibliography(t *testing.T) { + content := ` +--- +--- +--- +bibliography: testdata/bibliography.bib +... +testContent +` + expected := "testContent
\n" + runCiteprocTest(t, content, expected) +} + +func TestCiteprocWithExplicitCitation(t *testing.T) { + content := ` +--- +--- +--- +bibliography: testdata/bibliography.bib +... +@Doe2022 +` + expected := `Doe and Mustermann +(2022)
+