Setting a template based on YAML metadata blocks

Setting a template based on YAML metadata blocks

[JJ]

Hello, I've been acquainting myself with pandoc for the past few days.
It's quite neat. I particularly do like pandoc's markdown flavour:
it's everything I've ever wanted out of such an extension! I had some
questions that I've been unable to find answers to in the manpage or
elsewhere, however.

Is it possible to specify a template that pandoc is to use in a YAML
metadata block? Presumably this would only work with --standalone.
I've attempted `template: ` after seeing it elsewhere and hoping it
may work, but no dice. This seems like a common enough use case that
I'd imagine there is an option I am missing: or perhaps people on this
mailing list have external solutions. (though I was hoping to avoid
the use of sed: for no reason other than I've only had to use pandoc
in my script so far, which has been quite neat)

Also, what is best practice for "including" HTML fragments in pandoc?
I've found nothing in pandoc for this purpose so far - which, well,
makes a lot of sense. I was planning on first trying to rework things
to rely entirely on templates, and then in the event of failure just
sed-ing it up. But I harbour some concerns about accidentally
replacing text strings or code blocks.

Also also I am curious: what is the background behind *default* html
templates needing the .html5 extension, but regular html templates
using .html? This threw me for a bit of a loop for a bit.

-- JJ

Re: Setting a template based on YAML metadata blocks

[Bastien DUMONT]

To my knowledge, it is not possible neither to specify the path to a template file in the header nor to include the template itself in it. However, the template variable can be used in a defaults file.

You can include raw code by adding the name of the targeted format preceded by = in the attributes of a code block or a code inline:

```{=html}
<br/>
```


Le Tuesday 01 August 2023 à 10:16:07PM, JJ a écrit :
> Hello, I've been acquainting myself with pandoc for the past few days.
> It's quite neat. I particularly do like pandoc's markdown flavour:
> it's everything I've ever wanted out of such an extension! I had some
> questions that I've been unable to find answers to in the manpage or
> elsewhere, however.
> 
> Is it possible to specify a template that pandoc is to use in a YAML
> metadata block? Presumably this would only work with --standalone.
> I've attempted `template: ` after seeing it elsewhere and hoping it
> may work, but no dice. This seems like a common enough use case that
> I'd imagine there is an option I am missing: or perhaps people on this
> mailing list have external solutions. (though I was hoping to avoid
> the use of sed: for no reason other than I've only had to use pandoc
> in my script so far, which has been quite neat)
> 
> Also, what is best practice for "including" HTML fragments in pandoc?
> I've found nothing in pandoc for this purpose so far - which, well,
> makes a lot of sense. I was planning on first trying to rework things
> to rely entirely on templates, and then in the event of failure just
> sed-ing it up. But I harbour some concerns about accidentally
> replacing text strings or code blocks.
> 
> Also also I am curious: what is the background behind *default* html
> templates needing the .html5 extension, but regular html templates
> using .html? This threw me for a bit of a loop for a bit.
> 
> -- JJ
> 
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CABHcm%3Dpt_xyOKPCvieJH-QNvArZnCosb_h7xp4g_0RNJ0EECgQ%40mail.gmail.com.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/ZMoNWdOmQQPWXIqe%40localhost.

Re: Setting a template based on YAML metadata blocks

[John MacFarlane]

> On Aug 1, 2023, at 11:16 PM, JJ <jj-pl4xscvadcE@public.gmane.org> wrote:
> 
> Hello, I've been acquainting myself with pandoc for the past few days.
> It's quite neat. I particularly do like pandoc's markdown flavour:
> it's everything I've ever wanted out of such an extension! I had some
> questions that I've been unable to find answers to in the manpage or
> elsewhere, however.
> 
> Is it possible to specify a template that pandoc is to use in a YAML
> metadata block? Presumably this would only work with --standalone.
> I've attempted `template: ` after seeing it elsewhere and hoping it
> may work, but no dice. This seems like a common enough use case that
> I'd imagine there is an option I am missing: or perhaps people on this
> mailing list have external solutions. (though I was hoping to avoid
> the use of sed: for no reason other than I've only had to use pandoc
> in my script so far, which has been quite neat)

No.  You can use a defaults file for this.  We try to separate metadata from processing instructions.

> Also, what is best practice for "including" HTML fragments in pandoc?
> I've found nothing in pandoc for this purpose so far - which, well,
> makes a lot of sense. I was planning on first trying to rework things
> to rely entirely on templates, and then in the event of failure just
> sed-ing it up. But I harbour some concerns about accidentally
> replacing text strings or code blocks.

I'd need more information about what exactly you're trying to do.  In the template, you could include a variable and then populate it from a file using --variable myvar=$(cat myfile.html). In the document itself, there's no built-in way to do this, but you could use a small Lua filter to replace some element of the text (say, a code block marked with the file name to be included) with raw HTML from a file, which would be passed on unmolested to the output.

> Also also I am curious: what is the background behind *default* html
> templates needing the .html5 extension, but regular html templates
> using .html? This threw me for a bit of a loop for a bit.

html4 and html5 are separate output formats (but `html` defaults to `html5`).  That's why.  The templates are a bit different.


> -- JJ
> 
> -- 
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CABHcm%3Dpt_xyOKPCvieJH-QNvArZnCosb_h7xp4g_0RNJ0EECgQ%40mail.gmail.com.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/6CAC3AED-3628-4F25-BBB9-D3CEA9CECA36%40gmail.com.

Re: Setting a template based on YAML metadata blocks

[JJ]

> I'd need more information about what exactly you're trying to do.

Oh, I've just been playing around with using pandoc as an SSG
("including" my website's header across pages) to get a sense for how
it works. (yes i know, there are nice frameworks like hakyll - this is
very much just for learning!). A Lua filter seems nice.

> html4 and html5 are separate output formats (but `html` defaults to `html5`).  That's why.  The templates are a bit different.

Interesting, the behavior I'm seeing might be a bug then. Only
`default.html5` works as a default HTML template, placing
`default.html` in `data-dir/templates/` does not override anything.
Then also only files ending in `.html`, not `.html5`, seem to be
referenceable without the extension with the template flag (ex. --to
html --template "funky" only works if a `funky.html` exists, not
`funky.html5`).

On Wed, Aug 2, 2023 at 9:23 AM John MacFarlane <fiddlosopher@gmail.com> wrote:
>
>
>
> > On Aug 1, 2023, at 11:16 PM, JJ <jj-pl4xscvadcE@public.gmane.org> wrote:
> >
> > Hello, I've been acquainting myself with pandoc for the past few days.
> > It's quite neat. I particularly do like pandoc's markdown flavour:
> > it's everything I've ever wanted out of such an extension! I had some
> > questions that I've been unable to find answers to in the manpage or
> > elsewhere, however.
> >
> > Is it possible to specify a template that pandoc is to use in a YAML
> > metadata block? Presumably this would only work with --standalone.
> > I've attempted `template: ` after seeing it elsewhere and hoping it
> > may work, but no dice. This seems like a common enough use case that
> > I'd imagine there is an option I am missing: or perhaps people on this
> > mailing list have external solutions. (though I was hoping to avoid
> > the use of sed: for no reason other than I've only had to use pandoc
> > in my script so far, which has been quite neat)
>
> No.  You can use a defaults file for this.  We try to separate metadata from processing instructions.
>
> > Also, what is best practice for "including" HTML fragments in pandoc?
> > I've found nothing in pandoc for this purpose so far - which, well,
> > makes a lot of sense. I was planning on first trying to rework things
> > to rely entirely on templates, and then in the event of failure just
> > sed-ing it up. But I harbour some concerns about accidentally
> > replacing text strings or code blocks.
>
> I'd need more information about what exactly you're trying to do.  In the template, you could include a variable and then populate it from a file using --variable myvar=$(cat myfile.html). In the document itself, there's no built-in way to do this, but you could use a small Lua filter to replace some element of the text (say, a code block marked with the file name to be included) with raw HTML from a file, which would be passed on unmolested to the output.
>
> > Also also I am curious: what is the background behind *default* html
> > templates needing the .html5 extension, but regular html templates
> > using .html? This threw me for a bit of a loop for a bit.
>
> html4 and html5 are separate output formats (but `html` defaults to `html5`).  That's why.  The templates are a bit different.
>
>
> > -- JJ
> >
> > --
> > You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> > To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> > To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CABHcm%3Dpt_xyOKPCvieJH-QNvArZnCosb_h7xp4g_0RNJ0EECgQ%40mail.gmail.com.
>
> --
> You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/6CAC3AED-3628-4F25-BBB9-D3CEA9CECA36%40gmail.com.

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/CABHcm%3DrAT_j28acnFL-NBAZpQjQrtxPKXZ7KMT4MjSqZNnjbOg%40mail.gmail.com.

Re: Setting a template based on YAML metadata blocks

[jcr]

[-- Attachment #1.1: Type: text/plain, Size: 5786 bytes --]

There's a pandoc plugin <https://github.com/pelican-plugins/pandoc-reader> 
for Pelican, and with it you can choose a template with YAML metadata. When 
I set up a website with it earlier this year, I toyed with the idea of 
writing my own SSG as a script to run with `pandoc lua`. Such a script 
could read configuration files in YAML or JSON, find Markdown or files to 
process, use `pandoc.read` to parse them and `pandoc.write` to write them. 
The file's metadata is accessible to the script after `pandoc.read`, so it 
could be used to select a template. The advantage to writing an SSG this 
way is that it would be much faster than invoking the pandoc executable 
once for each file. However, existing SSGs have knowledge built into them 
about Web technologies and issues like SEO, and it would take time and 
study to replicate those. So while I really liked the idea of a `pandoc 
lua` SSG, I couldn't justify spending the time to build one.

On Thursday, August 3, 2023 at 3:11:42 AM UTC-4 JJ wrote:

> > I'd need more information about what exactly you're trying to do.
>
> Oh, I've just been playing around with using pandoc as an SSG
> ("including" my website's header across pages) to get a sense for how
> it works. (yes i know, there are nice frameworks like hakyll - this is
> very much just for learning!). A Lua filter seems nice.
>
> > html4 and html5 are separate output formats (but `html` defaults to 
> `html5`). That's why. The templates are a bit different.
>
> Interesting, the behavior I'm seeing might be a bug then. Only
> `default.html5` works as a default HTML template, placing
> `default.html` in `data-dir/templates/` does not override anything.
> Then also only files ending in `.html`, not `.html5`, seem to be
> referenceable without the extension with the template flag (ex. --to
> html --template "funky" only works if a `funky.html` exists, not
> `funky.html5`).
>
> On Wed, Aug 2, 2023 at 9:23 AM John MacFarlane <fiddlo...@gmail.com> 
> wrote:
> >
> >
> >
> > > On Aug 1, 2023, at 11:16 PM, JJ <j...-pl4xscvadcE@public.gmane.org> wrote:
> > >
> > > Hello, I've been acquainting myself with pandoc for the past few days.
> > > It's quite neat. I particularly do like pandoc's markdown flavour:
> > > it's everything I've ever wanted out of such an extension! I had some
> > > questions that I've been unable to find answers to in the manpage or
> > > elsewhere, however.
> > >
> > > Is it possible to specify a template that pandoc is to use in a YAML
> > > metadata block? Presumably this would only work with --standalone.
> > > I've attempted `template: ` after seeing it elsewhere and hoping it
> > > may work, but no dice. This seems like a common enough use case that
> > > I'd imagine there is an option I am missing: or perhaps people on this
> > > mailing list have external solutions. (though I was hoping to avoid
> > > the use of sed: for no reason other than I've only had to use pandoc
> > > in my script so far, which has been quite neat)
> >
> > No. You can use a defaults file for this. We try to separate metadata 
> from processing instructions.
> >
> > > Also, what is best practice for "including" HTML fragments in pandoc?
> > > I've found nothing in pandoc for this purpose so far - which, well,
> > > makes a lot of sense. I was planning on first trying to rework things
> > > to rely entirely on templates, and then in the event of failure just
> > > sed-ing it up. But I harbour some concerns about accidentally
> > > replacing text strings or code blocks.
> >
> > I'd need more information about what exactly you're trying to do. In the 
> template, you could include a variable and then populate it from a file 
> using --variable myvar=$(cat myfile.html). In the document itself, there's 
> no built-in way to do this, but you could use a small Lua filter to replace 
> some element of the text (say, a code block marked with the file name to be 
> included) with raw HTML from a file, which would be passed on unmolested to 
> the output.
> >
> > > Also also I am curious: what is the background behind *default* html
> > > templates needing the .html5 extension, but regular html templates
> > > using .html? This threw me for a bit of a loop for a bit.
> >
> > html4 and html5 are separate output formats (but `html` defaults to 
> `html5`). That's why. The templates are a bit different.
> >
> >
> > > -- JJ
> > >
> > > --
> > > You received this message because you are subscribed to the Google 
> Groups "pandoc-discuss" group.
> > > To unsubscribe from this group and stop receiving emails from it, send 
> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> > > To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pandoc-discuss/CABHcm%3Dpt_xyOKPCvieJH-QNvArZnCosb_h7xp4g_0RNJ0EECgQ%40mail.gmail.com
> .
> >
> > --
> > You received this message because you are subscribed to the Google 
> Groups "pandoc-discuss" group.
> > To unsubscribe from this group and stop receiving emails from it, send 
> an email to pandoc-discus...-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
> > To view this discussion on the web visit 
> https://groups.google.com/d/msgid/pandoc-discuss/6CAC3AED-3628-4F25-BBB9-D3CEA9CECA36%40gmail.com
> .
>

-- 
You received this message because you are subscribed to the Google Groups "pandoc-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pandoc-discuss+unsubscribe-/JYPxA39Uh5TLH3MbocFF+G/Ez6ZCGd0@public.gmane.org
To view this discussion on the web visit https://groups.google.com/d/msgid/pandoc-discuss/4a3a505c-cd43-4582-b098-ce27523a6ce8n%40googlegroups.com.

[-- Attachment #1.2: Type: text/html, Size: 7713 bytes --]

Re: Setting a template based on YAML metadata blocks

[John MacFarlane]

>> html4 and html5 are separate output formats (but `html` defaults to `html5`).  That's why.  The templates are a bit different.
> 
> Interesting, the behavior I'm seeing might be a bug then. Only
> `default.html5` works as a default HTML template, placing
> `default.html` in `data-dir/templates/` does not override anything.
> Then also only files ending in `.html`, not `.html5`, seem to be
> referenceable without the extension with the template flag (ex. --to
> html --template "funky" only works if a `funky.html` exists, not
> `funky.html5`).

That's expected behavior. The alias html = html5 only applies to
specifying values for `--to` or `--from`.