How to Publish a Blog with Glamorous Toolkit

2025/01/01

This blog is built with Glamorous Toolkit, a moldable, developer-focused environment. This environment has a knowledge base component. In it, I take many notes, some programming oriented, some of which end up in this blog. Below you'll learn how I promote some of these personal notes into a website you can reach on the internet.

Yet Another Static Site Generator?

Yes. And no. Glamorous Toolkit is self-documented with a 500+ page book that you can seamlessly read and interactively explore inside the environment. The whole book is also published as a website. This has the drawbacks of being a 'dead' version of the book, as one can't run code examples. At the same time, the online version is something to point to to start conversations on social media, etc.

Since I spend a lot of time inside Glamorous Toolkit (I'll use GT for short from now on), programming, writing, organizing my projects, analyzing my time, etc., I figured I'd bring the 'tools' to me, instead of the other way around, and publish my website directly from GT. Luckily, the code to turn the GT book (that lives inside the environment serialized as JSON files) into a website also lives in GT. Below we'll take a look at how, with some simple extension points as well as a couple of HACKS, I was able to re-use this machinery to publish my own (this) website.

Before we get into the nitty-gritty, 'bringing the tools to you', instead of the opposite is a central pillar of #MoldableDevelopment. Take a look at some of the conversation online around it.

LeHtmlBookExportCommandLineHandler

What now? Gt is an environment developed with Pharo Smalltalk among other technologies (Rust, FFI to C code, etc.). LeHtmlBookExportCommandLineHandler CommandLineHandler subclass: #LeHtmlBookExportCommandLineHandler instanceVariableNames: '' classVariableNames: '' package: 'Lepiter-HTML-Command Line' is the class one can subclass to turn a knowledge base into a website. If you expand the class name above, you will see that it subclasses CommandLineHandler Object subclass: #CommandLineHandler instanceVariableNames: 'commandLine session stdout stderr' classVariableNames: '' package: 'System-BasicCommandLineHandler-Base' , a class that assists with running Pharo code from the command line and dealing with command line flags, logging, etc. Having the logic in such a class means that it can enable workflows like publishing a webpage from a Continuous Integration (CI) pipeline without needing interactivity or the GT UI.

During development (both of the export code and/or writing) one can run the same code interactively from inside GT. This is rather useful as one can look at work in progress output in a browser without having to commit code/prose. Assuming you are already serving your assets locally with an instance of ZnServer Object subclass: #ZnServer instanceVariableNames: 'options sessionManager newOptions' classVariableNames: 'AlwaysRestart ManagedServers' package: 'Zinc-HTTP-Client-Server' (more on that later), you can run something like the code below to rebuild your website and view on your browser.

"Turning this page title into an html page path"
cleanTitle := [ :aString | 
	aString asLowercase
		collect: [ :aCharacter | aCharacter isAlphaNumeric ifTrue: [ aCharacter ] ifFalse: [ $- ] ] ].
thisPageHtmlPath := 'http://localhost:8080/'
		, (cleanTitle value: thisSnippet page title) , '.html'.
		
"Exporting to web page and opening in browser"
[ [ MyHtmlBookExportCommandLineHandler
	activateWith: (CommandLineArguments withArguments: {'--no-quit'}) ] timeToRun ]
	asAsyncFuture await
	asyncThen: [ :aDuration | 
		self
			inform: 'Build completed at: ' , DateAndTime now printToSeconds asString , ' in: '
					, (aDuration roundUpTo: 1 second) asString.
		WebBrowser openOn: thisPageHtmlPath ]

In fact, I just did to test the formatting of this exact page and the above Pharo code snippet in both desktop and mobile (modify code to visit root of your page to get you index.html.

The Tunables

Below is a more detailed explanation of the various methods one can override in their own subclass of LeHtmlBookExportCommandLineHandler CommandLineHandler subclass: #LeHtmlBookExportCommandLineHandler instanceVariableNames: '' classVariableNames: '' package: 'Lepiter-HTML-Command Line' to provide some defaults relevant to your webpage. One can also override many of these default values by providing them through command line arguments.

• The MyHtmlBookExportCommandLineHandler>>#activate activate | aBook aBookName aMainPage pagesToExclude | super activate. aBookName := self optionBookName. aBook := self findBookNamed: aBookName. aMainPage := self findMainPageInBook: aBook named: aBookName. pagesToExclude := (LeTableOfContentsVisitor tocForPage: aMainPage database tableOfContents) second children collect: #page. pagesToExclude := pagesToExclude , {aMainPage database tableOfContents} reject: [ :each | self unclassifiedPagesToKeep includes: each title ]. pagesToExclude collect: [ :aPage | MyGtBlogExport defaultOutputDirectory / (aPage title collect: [ :each | each isAlphaNumeric ifTrue: [ each asLowercase ] ifFalse: [ $- ] ]) , 'html' ] thenDo: [ :aFile | aFile ensureDelete ] : all command line handlers need to define this method. This is the entry point for your logic. For now, in my subclass, it calls super activate but added it in case I need to run my own logic before/after.

• LeHtmlBookExportCommandLineHandler>>#defaultBookName defaultBookName ^ nil : is where you define the name of your Lepiter database which will be exported as a webpage. This can be overridden through the book-name command line argument.

• LeHtmlBookExportCommandLineHandler>>#defaultMainPageName defaultMainPageName ^ nil : is the page that will be saved as index.html. This can be overriden through the main-page-name command line argument.

• MyHtmlBookExportCommandLineHandler>>#defaultPageTemplateFileName defaultPageTemplateFileName ^ (IceRepository registry detect: [ :aRepository | aRepository name = self class package name ]) repositoryDirectory / 'page-template.html' : this is an html file that serves as a template for each exported page in your database. It is out of the scope of this article for me to go through the changes I did to mine but I took the one defined for the GT book and heavily modified it. As of this writing, that file can be found in LeHtmlGtBookPiece>>#gtBook gtBook ^ self fromFile: FileLocator gtResource / 'feenkcom' / 'lepiter' / 'doc' / 'gtbook' / 'page-template.html' . This can be overriden through the page-template-file command line argument

• LeHtmlBookExportCommandLineHandler>>#defaultTargetDirName defaultTargetDirName ^ './' : it the output directory for your static assets. This can be overriden through the target-dir command line argument.

• LeHtmlBookExportCommandLineHandler>>#defaultHypertextReferenceBuilder defaultHypertextReferenceBuilder ^ LeExportFilenameAndExtensionHypertextReferenceBuilder new : defines if links between pages include the .html extension at the. This can be overriden with the href-builder command line argument. The base class includes file extension in the links while the GT book subclass does not. Which one you use (or if you create your own subclass to do something else) will have to do with your server settings and if it knows how to serve files without an .html extension as html. Unfortunately as of the time of this writing, this class does NOT control whether the page link is suffixed with the input lepiter page's LeUID LeModel subclass: #LeUID instanceVariableNames: 'uid' classVariableNames: '' package: 'Lepiter-Core-Model' (a UUID). We will discuss later how I was able to remove that. An issue has been opened on the GT repo so that this is more customizable by end users.

Html Templating

As most other templating frameworks, the GT html export finds and replaces values/variables inside curly brackets, in this case single (not double) curly brackets (i.e. {myValueToBeTemplated}). If we look at the default template file, you will find values to be templated match the values defined in LeHtmlGtBookPiece>>#initialize initialize super initialize. formatPiece := LeHtmlFormatPiece new at: #title put: LeHtmlPageTitlePiece; at: #titleAttribute put: LeHtmlPageTitleAttributePiece; at: #descriptionAttribute put: LeHtmlPageDescriptionAttributePiece; at: #urlAttribute put: LeHtmlPageUrlAttributePiece; at: #gtVersion put: LeHtmlGToolkitVersionPiece; at: #navigation put: LeHtmlNavigationPiece; at: #content put: LeHtmlPagePiece; at: #date put: LeHtmlDatePiece; at: #author put: LeHtmlAuthorPiece . Both that class and all the ones defined in the initialize method have their own implementations of LeHtmlFormatPiece>>#writeWithContext: writeWithContext: aContext "Like String>>#format: format the string template using the args given" | input currentChar | input := template readStream. [ input atEnd ] whileFalse: [ (currentChar := input next) == ${ ifTrue: [ | expression index piece | expression := input upTo: $}. index := Integer readFrom: expression ifFail: [ expression ]. piece := self at: index. piece writeWithContext: aContext. ] ifFalse: [ currentChar == $\ ifTrue: [ input atEnd ifFalse: [ aContext html << input next ] ] ifFalse: [ aContext html << currentChar ] ] ] . That class scanes the template file for values to be templated, then dispatches to the apropriate class. The other classes do the actual rendering to html.

One should familiarize themselves with the interplay between these classes if one is going to use a custom template file or even create their own custom template values/writers. To see how the different classes work look at the Lepiter-HTML under the Piece - Model tag. All those classes make use of the TLeHtmlPiece Trait named: #TLeHtmlPiece instanceVariableNames: '' package: 'Lepiter-HTML-Piece - Model' Trait.

The HACKS

Below is a list of things I wanted to do different than the GT book which did not have obvious extension points so I had to override some methods by creating extension methods in my packages and by attaching instances of Pharo's all powerful MetaLink Object subclass: #MetaLink instanceVariableNames: 'arguments condition conditionArguments control level metaObject nodes selector options' classVariableNames: '' package: 'Reflectivity-Core' class to some methods.

• By default, the html export appends UUIDs to page names. This is not someting that is desired in all circumstances and I definitely didn't want it on my site. To fix this, at class initialization time, I register a MetaLink in the following code MyHtmlBookExportCommandLineHandler>>#overrideBuildPageLink overrideBuildPageLink | method | method := [ LeExportPageLinksBuilder >> #buildPageLink: ] on: KeyNotFound do: [ nil ]. method ifNotNil: [ | ast link existingMetaLink | existingMetaLink := MetaLink allInstances detect: [ :aMetaLink | aMetaLink methods anySatisfy: [ :aMethod | aMethod methodClass = method methodClass and: [ aMethod selector = method selector ] ] ] ifNone: [ nil ]. existingMetaLink ifNil: [ ast := method ast. link := MetaLink new metaObject: [ :anArgument | thisContext sender receiver myBuildPageLink: anArgument ]; selector: #value:; control: #instead; arguments: #(#context). ast link: link ] ] . That makes it so that LeExportPageLinksBuilder>>#myBuildPageLink: myBuildPageLink: aPageorContext | aTitle anId aFileName aPage aResult | aPage := aPageorContext isContext ifTrue: [ aPageorContext arguments first ] ifFalse: [ aPage ]. aPage == self mainPage ifTrue: [ ^ LeExportBookMainPageLink new page: aPage; fileName: self mainFileName; fileExtension: self fileExtension ]. aTitle := aPage title asString collect: [ :each | each isAlphaNumeric ifTrue: [ each asLowercase ] ifFalse: [ $- ] ]. anId := self sequencer nextIdFromPage: aPage. aFileName := aTitle. aResult := LeExportBookPageLink new page: aPage; fileName: aFileName; fileExtension: self fileExtension; id: anId. ^ aResult is run as opposed to the original method. Running the code below gets you a diff of both methods

GtDiffBuilder
		computeDifferencesFrom: (LeExportPageLinksBuilder>>#buildPageLink:) sourceCode
		to: (LeExportPageLinksBuilder>>#myBuildPageLink:) sourceCode
		using: GtSmaCCDiffSplitter forPharo

• The html export has a baseUrl value that is useful as it gets templated into meta properties in the html output. Currently it's default value is 'https://book.gtoolkit.com' and although the class has a setter for that value, how the code is run doesn't allow to reach it. I've also attached a MetaLink. This one is of after type so after LeHtmlPageUrlAttributePiece Object subclass: #LeHtmlPageUrlAttributePiece uses: TLeHtmlPiece instanceVariableNames: 'baseUrl' classVariableNames: '' package: 'Lepiter-HTML-Piece - Model' is initialized, we override the default value by using it's setter method. See MyHtmlBookExportCommandLineHandler>>#overrideBaseUrl overrideBaseUrl | method | method := [ LeHtmlPageUrlAttributePiece >> #initialize ] on: KeyNotFound do: [ nil ]. method ifNotNil: [ | ast link existingMetaLink | existingMetaLink := MetaLink allInstances detect: [ :aMetaLink | aMetaLink methods anySatisfy: [ :aMethod | aMethod methodClass = method methodClass and: [ aMethod selector = method selector ] ] ] ifNone: [ nil ]. existingMetaLink ifNil: [ ast := method ast. link := MetaLink new metaObject: [ thisContext sender receiver baseUrl: MyHtmlBookExportCommandLineHandler defaultBaseUrl ]; selector: #value; control: #after; arguments: #(). ast link: link. ^ link ] ifNotNil: [ ^ existingMetaLink ] ] for details.

• I wanted headers to be clickable as anchor links so people could link to specifc sections of an article. This issuewas merged upstream and now works. This method had original fix on my end LeHtmlTextSnippetVisitor>>#myVisitHeader: myVisitHeader: aHeader | escapedHeader | self flag: #KEEP. "Keep for blog post reason." exportedNodes add: aHeader. escapedHeader := (((aHeader parts collect: #content) joinUsing: '') collect: [ :aCharacter | aCharacter isAlphaNumeric ifTrue: [ aCharacter ] ifFalse: [ $- ] ]) trimBoth: [ :each | each = $- ]. context html tag: 'a' attributes: {'href'. '#' , escapedHeader. 'style'. 'text-decoration: unset;'} do: [ context html tag: 'h' , (aHeader headerLevel + 1) asString attributes: {'id'. escapedHeader} do: [ self visitContent: aHeader ] ] TODO: Delete visitXXX method so upstream is picked up

• No syntax highlighting of Pharo snippets in the html export. For more details on the solution for this, see The Visitor Pattern.

• When exporting text snippets, new lines are added in between individual snippets, but newlines were not being preserved inside snippets. This monstrosity of a method fixes that LeHtmlTextSnippetVisitor>>#visitString: visitString: aString exportedNodes add: aString. aString parts ifNotEmpty: [ aString parts first isHeaderNode ifFalse: [ | collection isLineBreak paragraphs textNodes | isLineBreak := [ :aLeTextNode | aLeTextNode startPosition = aLeTextNode stopPosition and: [ aLeTextNode text value first isLineBreak ] ]. collection := OrderedCollection new. textNodes := aString sortedChildren. paragraphs := (textNodes splitOn: [ :each | isLineBreak value: each ]) reject: #isEmpty. paragraphs do: [ :someLeTextNodes | collection add: someLeTextNodes. collection add: (textNodes select: [ :aLeTextNode | (someLeTextNodes sortBlock value: someLeTextNodes last value: aLeTextNode) and: [ someLeTextNodes sortBlock value: aLeTextNode value: (paragraphs after: someLeTextNodes ifAbsent: [ {aLeTextNode} ]) first ] ]) ]. collection := collection reject: #isEmpty. collection do: [ :someLeTextNodes | (isLineBreak value: someLeTextNodes first) ifTrue: [ | newLines | newLines := someLeTextNodes size - 2. newLines > 0 ifTrue: [ newLines timesRepeat: [ context html tag: #br ] ] ] ifFalse: [ context html tag: #p do: [ self acceptNodes: someLeTextNodes ] ] ]. ^ aString ] ]. ^ self visitContent: aString . Unftortunately, it was not as easy as wrapping text snippets in a <pre> tag and calling it a day.

Local Hosting

It's convenient to deploy my site locally while I'm developing/testing. To quickly bring up a ZnServer Object subclass: #ZnServer instanceVariableNames: 'options sessionManager newOptions' classVariableNames: 'AlwaysRestart ManagedServers' package: 'Zinc-HTTP-Client-Server' that serves your asset folder locally one can run the below code. I have this tied to a <gtAction> in my repo so that I can enable/disable it easily from a button.

ZnServer startDefaultOn: 8080.
ZnServer default
	delegate: (ZnStaticFileServerDelegate new directory: MyGtBlogExport servingDirectory)

Pushing to Prod

This site is hosted on Cloudflare Pages. I have decided to separate the blog generation machinery and the static output into two different repos. As I work on machinery improvements and/or write articles I deploy locally. When I'm ready to publish a new article I change the output directory to my assets repo and commmitting on that repo will trigger the deploy to cloudflare pages (both for branch previews and pushes to prod).

My usage keeps me in the free tier of cloudflare pages and I like that pages are served on paths excluding the .html file extension. If I later need dynamic content I like that I can do that in cloudflare pages in a 'serverless' fashion.