search

etiennebacher / altdoc

Alternative to pkgdown to document R packages
https://altdoc.etiennebacher.com
Other
68 stars 9 forks source link

Why `format: md`? #296

Open eitsupi opened 1 month ago

eitsupi commented 1 month ago

The format md is not mentioned in the Quarto reference, so I think it should not be used by default. https://github.com/etiennebacher/altdoc/blob/011cea52005a4c269c9c733847cbd8a5a8cd85f4/R/qmd2md.R#L31-L36

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 commented 1 month ago

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 commented 1 month ago

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.

image

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 commented 1 month ago

@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 commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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

eitsupi commented 1 month ago

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 commented 1 month ago

@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 commented 1 month ago

@grantmcdermott Thanks for the detailed reply!

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