RFI: GitHub Actions Static Publishing Script

[boris]

I recently set up a LogSeq based notes repository at https://notes.ToolsForThought.rocks

This is a statically published version of a LogSeq source, which is roughly equivalent to a TiddlyWiki.

I found the LogSeq Publish action in the GitHub Marketplace Logseq Publish · Actions · GitHub Marketplace · GitHub

You can add it to any repo containing LogSeq content, and it will automate turning it into static content and publishing it to GitHub Pages.

GitHub Actions Static Publishing

I know that TW has various static publishing commands. I’ve struggled with them locally on my desktop, and then I need to manually check those files in and commit them to get them actually published. By which time I’ve just created 5 new tiddlers and fixed some typos and I need to create static commit push to GitHub all over again.

What I need is a way to add GH Actions to a repo containing either a single file wiki or individual Tiddler wiki and publish as static content.

The workflow would generally be local editing of a TW - eg TiddlyDesktop, running a local NodeJS, etc

This should be compatible with the Git Service Saver too.

Minimum: GH Actions YML

Create a GitHub Actions compatible YML formula that advanced users can copy into their local GitHub Workflows and use and customize as needed

Since GH Pages can choose either a branch or a sub folder in the main branch, this is what should be supported.

There may be other GH Actions that help with portions of this. At minimum this is constructing a script where it is clear what options are being passed to TW static publishing commands and resulting in a folder that contains the static version of the TW.

Package

Iterate over the script and turn it into a repo that can be called from any GH Action.

The minimum script is modified to use the repo and used as an example / getting started file.

See GitHub - pengx17/logseq-publish: Logseq Publish Action for an example of what this might look like. This likely means being comfortable with Docker.

Stretch goal: create and publish to GitHub Marketplace

Take the extra steps to package everything and publish to the marketplace.

Not in scope

There are many different ways to create and modify static publishing templates. None of that work is included here, except to the extent that the script needs to know about the command line switches and options that static publishing supports.

What this enables

This would create one default way to get TiddlyWiki content published as static content.

This makes it more likely to choose TiddlyWiki for all sorts of web projects, since static content is easier to link to, search, and customize for regular web browsing than the dynamic version.

Who is the audience

This targets medium to advanced technical users. I expect this to lead to a flurry of activity as many people can use the script in personal projects.

Related Resources

Turns out @saqimtiaz did some work about a year ago to automatically build a single file wiki and publish it from a multi Tiddler check in GitHub - saqimtiaz/TW5-github-actions-example: Example of how to use Github Actions to build and publish a TiddlyWiki

There may very well be existing GH Actions that people have built themselves! Please share any resources you find.

[boris]

I’m calling the first stage of suggesting a project for TiddlyWiki to be a Request for Interest or #rfi

This is a first draft with some background and a description of what success looks like.

Developers who are interested might comment and ask questions, other people interested in the project could pledge support, share their own requirements and use cases.

If it generally seemed like there was enough interest — I’d chip in for this! — then it gets posted as a project.

Once posted, we’d as a community want to help with a marketing push to find others who are interested in using a feature and chipping in. Main TiddlyWiki account, everyone sharing on their own channels, and generally doing a bit of a push to get the word out.

---

I’ll state my intent below:

I would be happy to pay a $100 one off honorarium to someone who could just build a GH Action YML file.

My personal belief is that software needs maintenance, small feature add ons, and answering questions from users, so mostly it should get funded over time. So I’d be in for $10/month for the first year as well.

[saqimtiaz]

This sounds like a fun one to tinker with and I agree that it would be helpful to many. For example, automatically generating RSS and JSON feeds is just another version of static publishing.

In terms of needing to customize for individual use like which tiddlers to export to static, I have found it useful to have the ability to specify this via a tiddler, which can be overridden by a commandline argument. For most TiddlyWiki users this is a pretty friendly workflow as they can make all configuration changes via TiddlyWiki itself.

I assume that customizing the default static export templates is not included in the scope of this work, it would be good to clarify this.

[boris]

@saqimtiaz

I assume that customizing the default static export templates is not included in the scope of this work, it would be good to clarify this.

Yep! All work on customizing the static export templates is on the TW input side of the house: insert TW file or tiddlers, have a “standard” static export, get HTML assets out.

If there are ways to read from TW in such a way that this customizes flows in the GH Action — great! Put that in the Stretch goals.

I do think building up useful components and recipes and defaults like RSS/JSON feeds would be great to include in docs around this, but it’s also all native TW stuff that many more people here could contribute to.

[saqimtiaz]

I would really like to see this work get done, as I think it really opens the doors for a lot of opportunities.

For example, it would make publishing a static site or blog complete with an RSS feed so easy that any user could do so by just hitting save in a TiddlyWiki. This would further open the door for focusing on creating better static site templates, all of which would be wikitext, HTML and CSS work and would be an excellent use of the proposed marketplace. In other words, there is an opportunity to be had there to be both open up the use of TiddlyWiki as a tool to publish static websites to non-tech savvy users, but also to create an opportunity for those skilled with HTML and CSS to be able to generate an income while contributing to the community and building up a set of templates that everyone could use.

This work is a first step towards getting there.

While I could easily put my hand up and say that I will work on it, I would much rather that someone else got involved and took this opportunity. If you are familiar at all with static publishing from TiddlyWiki, this is not a lot of work.

[saqimtiaz]

@linonetwo @sttot @oeyoews @oflg just wondering if you guys have worked with either static file publishing and/or Github Actions for TiddlyWiki?

[oeyoews]

@saqimtiaz yeah，I often use github actions to build static files and update my own plugin library,build in less than a minute
scripts

action file

[oeyoews]

maybe write a github action for tiddlywiki on github marketplace, it would be more convenient

[boris]

Yes that’s where I’d like it to end up, so there is a “just works” option for many people.

[oeyoews]

I also attempt to try to create a github action for tiddlywiki (since this is my first attempt and not very familiar with it, it might be a bit slow)

[oeyoews]

hugo action example

[Sttot]

The CPL I designed before was a JSON file generator using a CI/CD script.

I recently developed another solution myself to generate HTML static blogs (with metadata) using TiddlyWiki content, the generated blogs are at gk0wk.github.io (all written in Chinese, nothing to see here, just wanted to serve as an example) - the related code I haven’t open sourced yet, because I don’t know in what form to publish it.

BTW: it’s SSR(Server side render) not CSR (client side render)

[boris]

There are many SSG scripts. I currently use jekyll on my personal site.

Roughly this means putting TW and node in a Docker container and passing the correct switches to TiddlyWiki into an output folder.

The LogSeq Publish action uses a Docker image as starting point logseq-publish/action.yml at main · pengx17/logseq-publish · GitHub

This Jekyll Build action uses no Docker and just JS and Ruby so closer to what TW needs jekyll-action-ts/action.yml at master · limjh16/jekyll-action-ts · GitHub

[Mohammad]

@Sttot

gk0wk.github.io

Great stuff @Sttot. Thank you for sharing.

[saqimtiaz]

@oeyoews @Sttot we are discussing creating a Github Action or script for TiddlyWiki that can be used to build a static site every time new content is pushed to the repo. We can try to fund raise for this a little (perhaps via Open Collective) to provide a small thank you and some motivation for the developer.

Would either of you, or anyone you know, be interested in working on this?

[oeyoews]

@saqimtiaz Tiddlywiki repo looks like there are already some scripts to build static site.

@saqimtiaz

pushed to the repo

which repo?

[saqimtiaz]

The idea is to create an action that anyone can use in their GitHub repo, to build a static site from their TiddlyWiki and publish it with GitHub Pages.

This is meant to be something for end users to be able to use, and not for the official TW repo.

[oeyoews]

That would be easy to do if just used scripts, but not as user-friendly as github actions

[saqimtiaz]

Scripts can be the starting point. If we have a good documented script that accepts different arguments or environmental variables to customize the static rendering (which tiddlers to include etc), it can later be used to create a GitHub Action.

Edit: another option is a template repository with scripts configured that the user can clone to create their own repository with static site building configured.

[oeyoews]

Some configurations can be placed in the tiddlywiki.info file, such as building multiple html at the same time, custom directories, and tiddlywiki commands(It’s just that this file does not currently support comments, and the readability is not very friendly)