Does anyone know of a method of rendering a range of GitHub source as a code-block?
I found a plugin that will render a gist, but not an arbitrary code blob with a line range.
In my imagination, you would write some markdown like:
```cs https://github.com/mcneel/rhino-developer-samples/blob/6/rhinocommon/cs/SampleCsCommands/SampleCsAddNurbsCurve.cs#L19-L59 ```
and it would be rendered on the site as if the code-block was written in the markdown source.
My guess is someone has already done this any my search skills are poor.
2 Likes
I have been looking for the same thing and have not yet found a solution! This issue seems to lead in the right direction…
I am looking into it further and will reply here if I find a solution.
Word of warning that code can change especially references to specific lines, so you should use a commit reference in place of the branch.
Note also that a link to a file on github has a lot of github UI HTML on it. If you use the raw URL through the raw button on a file, you’ll seen plain text for the file and nothing else. Your solution will likely have to use that internally even if you don’t specify the raw URL as the argument.
There is a plugin I found for fetching code snippets by URL. Which could be adapted to embed markdown. And pass it a raw git file URL perhaps instead of relative URL.
Consider using Docsify. A JS package built on Vue for building a docs site using a base index.html, a configured theme and all your pages as markdown files.
I have a tutorial here for using embedding in Docsify. There are many ways, but a flow exists to target a raw GitHub source and to render md code as native code on the page (not as a code snippet)
https://michaelcurrin.github.io/docsify-js-tutorial/#/?id=embed
Docsify works great on GH Pages. It is an alternative to Jekyll though - you have to set a .nojekyll value to prevent the site rendering through Jekyll (same as if you have a React site built to a gh-pages branch using a build step, though Docsify doesn’t need have a build step)
It supports some advanced things but generally I find I get a professional docs site than out writing any includes or layouts like one has to in Jekyll. (Yes you can use a theme in a Jekyll but I think every time I switch a theme something breaks or needs installing or configuring, docsify has 4 themes but it is only one line change to switch between them).
it is accessible as it doesn’t need Ruby or Jekyll and you don’t even need a local install step. Docsify gets fetched in the browser.
I have a template of a minimal Docsify site if you are interested GitHub - MichaelCurrin/docsify-js-template: A quickstart template for a markdown-based docs site
PS. Maybe you can figure out the frontend JS on Docsify that embeds code and use that on Jekyll?
Does Docsify accepts GH permalinks too? Same as what we can do in a README.md file and GH renders a code block for us?