Add support for language option in confluence code block macro about conflr HOT 15 CLOSED

You maybe use pandoc markdown using markdown or maybe commonmark as you use it after ? This is a pandoc output format.

Oh, thanks! I didn't know these variants. +fenced_code_blocks doesn't work, but markdown and commonmark works fine.

$ echo -e '``` r\n1 + 1\n```' > tmp.md
$ pandoc --to markdown_strict+fenced_code_attributes tmp.md 
    1 + 1
$ pandoc --to markdown tmp.md 
``` {.r}
1 + 1
```
$ pandoc --to commonmark tmp.md 
``` r
1 + 1
```

from conflr.

Oh, I see, thanks :)

from conflr.

Thanks, I didn't consider about this option (for a reason, I wrote below).

first what do you think ?

I think it's possible. Probably the loss of language is simply due to my lack of the knowledge about Pandoc's options... Do you know the right one to add here?

Or, even if the corresponding option cannot be used for some reason, we can mark the language option before converting it to md and restore the option after the conversion (I learnt this technique from formatR).

One thing I'm not sure is how Confluence handles the language option when the syntax highlight is not available. On my environment, it seems syntax highlighting of R is not supported (that's why I didn't think this option matters). Does your Confluence's code block support R?

from conflr.

Do you know the right one to add here?

I'll look into it, I think of some option that could work, but it may come from the markdown_strict format also. I don't know if this format support code with language attributes for highlight. I'll try.

To fully understand the design, why converting to markdown_strict using pandoc, then html using commonmak ? Is there a specific reason or a custom pandoc template for html would work ? I guess it is linked to #51 where a custom Rmarkdown format is discussed.

Does your Confluence's code block support R?

Not by default. I asked my confluence admin to add support for R language. You can easily define a new language
https://confluence.atlassian.com/doc/code-block-macro-139390.html#CodeBlockMacro-ConfiguretheCodeBlockmacro
It is using the brush syntax and I found on example to play with on the web in yihui's gist https://gist.github.com/yihui/1804862 - I used this one even if it is old but it works fine. I am sure it can be improve but I did not modify it yet. This could be another thing to work together.
I think a vignette could be added on how to configure confluence for this and those brush syntax related file could be included in the package for example.

One thing I'm not sure is how Confluence handles the language option when the syntax highlight is not available.

You are right, This is the drawback - I think confluence does not render code block correctly if language is unknown It does not default to one language.
I guess there should be an option in this package to opt-in or opt-out, depending which default behaviour you choose.

When we began with confluence, this was one of the first thing I looked into - how to get syntax highlighting correct for R chunk?
The second was : how to publish my Rmd directly as confluence page ? I was very happy to found your 📦 ! Works very well! but my 'first thing' is now missing as not R highlights.

from conflr.

Works very well! but my 'first thing' is now missing as not R highlights.

Oh..., thanks for your context! I see.

To fully understand the design, why converting to markdown_strict using pandoc, then html using commonmak ?

This is mainly in order to preview the page on RStudio; for previewing, RStudio requires base64-encoded images, but for posting to Confluence, we need paths to the image files. So, I found it convenient to generate an intermediate md and modify it in two ways.

Other small reasons I don't remember are related to the fact that the syntax of Confluence is not valid either as HTML or as XML. I struggled to tweak the document by heavily using xml2, but it sometimes errored and then I found using commonmark just works.

(#51 is just for convenience. e.g. Writing the page ID on the Rmd might make it easy to update a specific Confluence page periodically)

from conflr.

FWIW, it seems users see this error if the language is not supported on their Confluence.

from conflr.

I found why the language is lost... The default variant of md_document() is the original Markdown syntax (markdown_strict). It defines only "indented code block" and there's no "fenced code block":

https://daringfireball.net/projects/markdown/syntax#precode

So, it might be as easy as just specifying variant = "gfm", but I don't remember if I tried this (and failed?).

from conflr.

FWIW, it seems users see this error if the language is not supported on their Confluence.

Thanks ! That mean an opt-in mechanism can be required to activate only for those who have R language support. Some helpers and a vignette to add this support can be useful.

The default variant of md_document() is the original Markdown syntax (markdown_strict)

This is what I thought. Is it not possible to activate fenced code block with +fenced_code_blocks ?
You maybe use pandoc markdown using markdown or maybe commonmark as you use it after ? This is a pandoc output format.

I'll try to look into it today.

from conflr.

You have a really wide variety of output format
https://pandoc.org/MANUAL.html#general-options

Since last pandoc you even have a JIRA markup format ! Dev reprex use it now I think. but I am not sure it works for confluence. From my previous test the code block syntax is a bit different. May be it is worth the try though?

from conflr.

Hmm..., it seems Confluence's REST API doesn't accept markup documents directly and probably we need to convert it to storage format beforehand. But, it might be cleaner than the current implementation.

c.f. https://developer.atlassian.com/server/confluence/confluence-rest-api-examples/

from conflr.

Sorry, conflr's internals are messy and probably I don't have enough time to explain how to develop this feature... so instead I created a naive implementation (no opt-in mechanism is considered at the moment) for illustration: #55

from conflr.

@cderv
I updated #55 with an opt-in by setting options(conflr_supported_languages_extra = "r"). Could you try when you have time? I'm not yet sure if it's a good idea to pass this via option, though. Any suggestions are welcome!

from conflr.

Thanks !

I can try at work beginning of January next year.

Option is not so bad for an opt-in mechanism. In your translation process I think you may catch a language not in your default language and throws a message or a warning once that is the user want to have R highlighting in confluence, one should configures with its confluence admin then modifies option in R. Maybe it is not necessary and only users who will read the doc will know about this and its enough. 😄

Other solution I see is to add extra supported languages as an argument in your user-facing functions. I would imagine having to provide as function argument when posting (like venue in reprex). And if I want to set it up globally i would set up the option to change the default.

That make me thinks that we could ask confluence if they are willing to add R in the default language... I don't know how though... 🤔

from conflr.

I can try at work beginning of January next year.

Aw, sorry for disturbing you...

Thanks, I'll consider warnings. Sounds reasonable. For making it as an argument, I'm yet to see how to pass them, but I think I'll come up with some idea next year...

Have a nice holiday!

from conflr.

Aw, sorry for disturbing you...

Oh you are not disturbing at all !
Unfortunately, I do most of my open source activities on my time off. 😉

It just I won’t have a confluence website to test with until next year. 🤷‍♂️

from conflr.