Parsing GitHub Gist Embeds Into A Normalized Data Structure Using jSoup In ColdFusion

<cfscript>

	// This is the EMBED URL, except I've replaced the ".js" extension with ".json". This
	// provides us with the Gist data in a quasi-usable data format.
	// --
	// CAUTION: For simplicity of demo, I'm using ColdFusion's ability to read remote
	// files using the file I/O functions.
	gistData = deserializeJson(
		fileRead(
			"https://gist.github.com/bennadel/b41f05e9e5aef523153ef2c2a41efcb3.json"
		)
	);

	// All of the files in the Gist are rendered inside a single "div" property. In order
	// to make them more accessible / consumable, I'm going to parse the "div" property
	// and then break each file out into its own container.
	gistDoc = javaNew( "org.jsoup.Jsoup" )
		.parseBodyFragment( gistData.div )
	;
	// When the GitHub gist is rendered, it uses "white-space: pre" in order to maintain
	// indentation on a given line of code. By default, jSoup will remove leading and
	// trailing white space (during serialization of nodes) since it doesn't know anything
	// about CSS. In order to get jSoup to keep the leading white space / indentation, we
	// have to disable the pretty-print feature.
	gistDoc.outputSettings().prettyPrint( false );

	// Now, we want to locate each file NODE within the monolithic "div" DOM tree and map
	// it onto a normalized data structure.
	files = gistDoc
		.select( ".gist-file" )
		.map(
			( fileNode, i ) => {

				// When the Gist embed is delivered, all of the files are wrapped in a
				// common parent. However, now that we want to break the Gist up into
				// separate files, we need to re-wrap each file in the expected parent.
				// This is done primarily for CSS / styling reasons.
				fileNode = fileNode
					.wrap( "<div class='gist'></div>" )
					.parent()
				;

				// Since there's no JavaScript in the embed, there's no need to have
				// templates - not sure what purpose these would be serving (in our case).
				// They won't cause harm to be left in; but, they are added bloat.
				fileNode
					.select( "template" )
					.remove()
				;

				// We are taking it on faith that the file-names and the gist-files are
				// listed in the same order (this is not documented, but appears to be
				// consistent). 
				return([
					name: gistData.files[ i ],
					htmlContent: fileNode.outerHtml()
				]);

			}
		)
	;

	// Each Gist comes with its own stylesheet reference.
	// --
	// NOTE: I do not know how unique this stylesheet content is. The filename appears to
	// contain a hash (likely related to the contents of the stylesheet). As such, if I
	// were going to cache this locally, I'd likely use a hash of the content as well in
	// order to de-duplicate stylesheets across Gists. Also, by caching the CSS locally,
	// we will be breaking the "sourceMappingURL" value.
	cssContent = fileRead( gistData.stylesheet );

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	// At this point, we've read-in and parsed our GitHub Gist data into a predictable,
	// consumable data structure. Now, we can render it however we want. Note that we are
	// rendering each file separately.
	```
	<cfoutput>

		<style type="text/css">
			#cssContent#
		</style>
		<!---
			In order to override CSS properties in the Gist Embed stylesheet, we have to
			scope them to the BODY (as one means to increase the specificity of our styles
			vs the provided styles).
		--->
		<style type="text/css">
			body .gist .gist-file {
				border: 4px solid hotpink ;
			}
		</style>

		<h1>
			Gist: #encodeForHtml( gistData.description )#
		</h1>

		<p>
			There are #numberFormat( files.len() )# file(s) in this Gist.
			CSS content hash: #hash( cssContent ).lcase()#
		</p>

		<cfloop index="i" value="entry" array="#files#">

			<h2>
				(File #i#): <code><mark>#encodeForHtml( entry.name )#</mark></code>
			</h2>

			#entry.htmlContent#

		</cfloop>

	</cfoutput>
	```

	// ------------------------------------------------------------------------------- //
	// ------------------------------------------------------------------------------- //

	/**
	* I create a new Java class wrapper using the jSoup JAR files.
	*/
	public any function javaNew( required string className ) {

		var jarPaths = [
			expandPath( "./jsoup-1.16.1.jar" )
		];

		return( createObject( "java", className, jarPaths ) );

	}

</cfscript>