Why format: md?

[eitsupi]

The format md is not mentioned in the Quarto reference, so I think it should not be used by default.

altdoc/R/qmd2md.R

Lines 31 to 36 in 011cea5

	out <- evaluate::evaluate('quarto::quarto_render(
	input = path.expand(tar_file),
	output_format = "md",
	quiet = FALSE,
	as_job = FALSE,
	)', new_device = FALSE)

I also think that the specification by preamble is ignored because it is specified in the options of the render command.

Why not gfm or commonmark?
https://quarto.org/docs/reference/formats/markdown/commonmark.html

I noticed that the gfm extensions are not available due to the md being specified here (manifested due to #295).

Currently altdoc forces updates to README.md, so README.md rendered as gfm overwrites the one rendered as md, breaking the display.
(This was accidentally circumvented on the Quarto website, but should have happened before with other formats.)

I think it is likely that many static site generators are compatible with gfm, but I am not convinced.
At least as far as the README is concerned, it should be rendered as gfm.
(Ideally, altdoc should do nothing. It is the user's responsibility to update it.)

[etiennebacher]

I think this was just a remnant of the previous code that used R Markdown and not Quarto to render documents. Since it also worked with Quarto I didn't see a reason to change. I have no idea which one of gfm or commonmark should be preferred.

What kind of gfm extensions if broken because we specify output_format = "md"?

[eitsupi]

What kind of gfm extensions if broken because we specify output_format = "md"?

For example, you can see in tinytable's README that the footnotes are broken.

https://github.com/vincentarelbundock/tinytable/blob/cf5f3bfbb1ed4fef574540af443d065b693781a7/README.qmd#L32
https://github.com/vincentarelbundock/tinytable/blob/cf5f3bfbb1ed4fef574540af443d065b693781a7/README.md?plain=1#L31-L32
https://github.com/vincentarelbundock/tinytable/blob/cf5f3bfbb1ed4fef574540af443d065b693781a7/README.md?plain=1#L153-L154

It is not broken on the website, but this is only because altdoc has not used README.md for the Quarto website so far.

It is not broken in tinyplot's README, but that is probably because tinyplot does not commit the README.md updated by altdoc and manually renders the README.md as gfm.

https://github.com/grantmcdermott/tinyplot/blob/051fda9e298b76bdd1c39d7986f488b063770c53/README.md?plain=1#L34-L37
https://github.com/grantmcdermott/tinyplot/blob/051fda9e298b76bdd1c39d7986f488b063770c53/README.md?plain=1#L140-L144

[eitsupi]

@grantmcdermott I assume you have not committed the README.md updated by altdoc in the tinyplot package repository.
Do you think it is worth changing it so that altdoc no longer renders the README.qmd or README.Rmd (same as pkgdown)?

[etiennebacher]

Since CommonMark is defined as "A strongly defined, highly compatible specification of Markdown", I'd prefer using it over gfm that seems very Github centric.

[eitsupi]

Yes, for anything other than README, it is probably more appropriate to use commonmark.
However, given that gfm is commonly used for README, I expect that there are gfm extensions that are disabled by specifying commonmark (I'm not sure which ones, but I think task lists in general were gfm extensions).

[etiennebacher]

This distinction would go away by not rendering the README as you advocate, right?

[eitsupi]

Yes, I think the README is obviously special and needs to be handled separately (don't render, special function, special header).

The simplest way is skip rendeering.

[grantmcdermott]

@grantmcdermott I assume you have not committed the README.md updated by altdoc in the tinyplot package repository. Do you think it is worth changing it so that altdoc no longer renders the README.qmd or README.Rmd (same as pkgdown)?

Hi, not sure that I follow the discussion entirely (sorry; I read quickly). But, yes, what I do is render the README.md file manually with:

quarto render README.qmd --to gfm

This part of the workflow is actually the only real pain point that I have encountered with altdoc. (See related issue here.) But it also relates to the fact that altdoc's auto-rendering was messing up some README badges (see here).

[eitsupi]

@grantmcdermott Thanks for the detailed reply!

I think it would be better to turn off the automatic rendering of the README to simplify things.