rst support

[kootenpv]

Is there a way to test locally how .rst (restructured text) would look like on github?

[joeyespo]

I still don't have a strong intention to include this since GitHub's Readme API doesn't support it. But since this keeps coming up (#92, #37, #113), and with the newfound focus on the offline renderer (#35), it might be worth taking a serious look.

Keeping this open for discussion and implementation advice.

[pdurbin]

https://github.com/github/markup is described as "The code we use to render README.your_favorite_markup" so I would guess that the list of supported formats there (which includes .rst) matters more to users of grip than the list of supported formats for the API that grip calls ( https://developer.github.com/v3/markdown/ ). To end users of grip, the calling of that API probably feels like an implementation detail of how grip works internally.

https://github.com/github/markup/blob/master/lib/github/commands/rest2html appears to be the Python script GitHub uses to turn .rst files into HTML. I kind of feel like that whole library could/should be wrapped by grip or something similar. That way you'd get all the formats.

[mitar]

+1

[ulope]

As a workaround you can use readme_renderer which additionally has th eoption to ensure compatibility with PyPI

[bjodah]

One work around is to use rst2html.py, optionally with custom css, e.g. https://github.com/matthiaseisen/docutils-css

[polyzen]

https://github.com/sindresorhus/github-markdown-css

[joeyespo]

@polyzen Wow, awesome resource. Thanks for sharing here!

[reece]

Also consider restview. https://mg.pov.lt/restview/ No github style, unfortunately.

[kootenpv]

Perhaps @joeyespo could say: "yes, I would approve of a rst2html pull request", then I'm sure someone will want to pick this up :)?

[poppyschmo]

Also consider restview. https://mg.pov.lt/restview/ No github style, unfortunately.

@reece, while it's hit and miss, I've found the Warehouse/PyPI stylesheets at times produce a closer approximation of the GitHub look than the genuine article. Guessing the selectors are less discriminating. The source is all sass/scss, but the processed goods can be gotten easily enough.

>$ wget -q -nd -e robots=off -p -A "warehouse.*.css" https://pypi.org && mv ware*css warehouse.css
>$ restview --css warehouse.css,restview.css README.rst

Doesn't fix the whole over-sized heading thing, though. Injecting something like this via browser plugin, or whatever, seems to help:

Array.from(document.getElementsByTagName('h1')).forEach(el => el.outerHTML = el.outerHTML.replace(/<([/])?h1/g, "<$1h2"));

Edit: Actually, after glancing at @polyzen's GH source (instead of just rejecting it outright when it didn't work OOTB), it does seem the better choice, given a little finagling:

>$ sed -i "s/\.markdown-body/body/g" github-markdown.css

BTW, it's not worth messing with the .pl-* code-highlighting styles, IMO. For example, GitHub's .pl-k ("k" for keyword, apparently) corresponds to restview's .nb (Pygment's Name.Builtin). But all the Pygments stuff gets in-lined after anything passed as --css <my_styles.css>. Also, sometimes simply leaving out ,restview.css as a fallback yields nicer results.

// demote subheadings
Array.from(document.querySelectorAll("h1,h2,h3")).slice(1)
    .forEach(el => el.outerHTML = el.outerHTML
    .replace(/(<[/]?h)(\d)/g, (_, m, n) => m + (Number(n) + 1)));

P.S. @joeyespo, sorry for the non-grip chatter; I do use it, and it's amazing. C.C. @mgedmin

[kootenpv]

@poppyschmo This is really nice... for a hack.

[chey]

Just a thought here. One way to handle this could be to use something like pandoc to convert rst(s) to markdown on the fly, then use the markdown as you normally would.

[zellyn]

I ended up here because I tried rendering an org-mode file with grip just to see if it worked (it didn't!)