Skip to content

Embedding GitHub Source in blog entries

Glen Mazza edited this page Dec 11, 2019 · 7 revisions

TightBlog starting with version 3.6 provides the ability to embed GitHub source code into blog entries. (Example here) This is implemented as an endpoint in TightBlog that queries the GitHub source code and returns the source code to the blog entry via a JavaScript document.write(...) command.

The Thymeleaf template used to output the source code is located here, and customizable styling for same is located in the main CSS file for both the "gaurav" and "rolling" blogthemes (see the div.github* properties here).

To activate this functionality:

  1. In your application-tbcustom.properties file, set external.github.enabled=true. (This endpoint is disabled by default.)
  2. To help avoid this endpoint being used externally (it's publicly available if enabled), recommended to also set the external.github.whitelist property to just the specific projects you wish to show source code from. See the comments for this property for more details.
  3. GitHub's servers by default are hit once every six hours to get the source code (if a blog page containing the source code is requested), subsequent requests during this period retrieve a cached object stored by TightBlog. This means if you change the source code, it will take up to six hours to refresh on the blog page. This wait period can be adjusted via the githubSourceCache.timeoutHours property.
  4. Up to 500 source code files will be cached by TightBlog, this can be adjusted via the githubSourceCache.maxEntries.

To display source code in a blog entry:

Add a tag to the blog entry similar to as follows:

<script src="https://localhost/tightblog/gmazza/external/github/gmazza/blog-samples/raw/master/jaxws_handler_tutorial/client/src/main/java/client/ClientHandlers.java?height=300&start=5&end=5&linenums=false"></script>

Replacing "https://localhost/tightblog/gmazza" with the URL to your blog handle.

As shown in the above example, there are four optional parameters you can add to the src attribute:

Parameter Default Meaning
height as tall as needed to display all the source code The height of the github-source div to display the source code in, if shorter than the source code a vertical scroll bar will normally appear (browser-dependent)
start 0 The source code line to start showing, in case you wish to just show a snippet of the code instead of the entire file. The first line is represented by both 0 and 1, the second line is 2, etc.
end end of source The ending source line to show in case of showing snippets.
linenums true Whether or not to show line numbers in the left column.