emacs org-mode highlighting, not markup

[falloutphil]

Hi,

Linguist seems to support syntax highlighting for emacs org-mode:
https://github.com/github/linguist/blob/master/lib/linguist/languages.yml#L3758

but github seems to automatically render org as mark-up:
https://github.com/github/markup#markups

Whilst this is often useful, sometimes it would be better to have the raw org script syntax highlighted.

Is there a way to tell github to render org files as syntax-highlighted raw source, rather than rendering the markup?

[pchaigno]

What's the use case(s) for highlighting source files instead of rendering them?

[falloutphil]

For me - The rendering is pretty limited and will never cater for all use cases of org-mode. I do use it for writing documentation in github, and it is undoubtedly useful for that. But Org is more than just a HTML based markup language. With more sophisticated templates I am much more interested in reading the underlying config and code than I am looking at how it might look when rendered. In particular when HTML is not the target output of an org document.

I think both options should be available.

Case in point was this for me:
https://github.com/falloutphil/Misc/blob/master/cpd.org

This is a template that renders TODO lists to well formatted Latex tables. It has no purpose rendering to HTML, and actually looses some of the useful information in doing so:
https://raw.githubusercontent.com/falloutphil/Misc/master/cpd.org

I have other more complicated examples - an org script that produces drill-cards for learning Chinese for example - it can't render the cards of course as this would have to be a server-side dynamic generation of output, so it would be more useful to see the underlying structure in github.

The obvious analogy is HTML files - these are not rendered in github, for obvious reasons (external dependencies, security, etc). All the same reasons apply to org too (dynamic block generation, etc).

[lildude]

Is there a way to tell github to render org files as syntax-highlighted raw source, rather than rendering the markup?

Unfortunately not, and this isn't due to Linguist either. It's due to the way GitHub and markup behaves and neither offer an override mechanism. The best thing to do is contact GitHub support using the "Contact GitHub" link at the bottom of any page and log this as a feature request.

[pchaigno]

@lildude Couldn't we offer an override mechanism in Linguist if we define a special language entry for each rendered language? Then, (1) users could select that special language entry via our current overrides and (2) github-markup wouldn't render the files because it relies on Linguist to detect the language.

[lildude]

@pchaigno that could work but it feels out of place doing this from Linguist. I think it might also cause confusion when it comes to what language is detected, what to use, when and where, and where to log issues.

It would also be a partial solution as it appears the .gitattributes override method doesn't seem to affect markup rendering (I've not looked into why not) according to github/markup#1102 .

[pchaigno]

@lildude Ok, makes sense.

As an alternative, it might be possible to implement an override mechanism in https://github.com/github/markup.

[stale]

This issue has been automatically marked as stale because it has not had activity in a long time. If this issue is still relevant and should remain open, please reply with a short explanation (e.g. "I have checked the code and this issue is still relevant because ___."). Thank you for your contributions.

[falloutphil]

Responding to stale bot - the issue is still as relevant as when I opened it - no solution has been settled on just yet.

[pchaigno]

I think it has been clarified that the solution cannot be a change in Linguist. You might have more luck at https://github.com/github/markup.