Creating A Static Blog

2021/4/6 20:59

Overview

(This is generated from the examples in https://github.com/welford/twstaticblog/ 👍 )

I keep notes on various things in Tiddlywiki and it is very useful to be able to export my blog from the same resource. Currently TiddlyWiki has a good but bare bones static export mechanism, I have made some plugins to enable something more along the lines of what I want in a static blog.

Put simply, if I tag any tiddler within my tiddlywiki with a special tag e.g. blog then that tiddler will be included as part of my blog when I run the export batch file. The tags used to specify what is and what isn't an export target are configurable.

I use these plugins to generate http://phasersonkill.com/

The code for this example can be found here: https://github.com/welford/twstaticblog (see example folder for this very file)

this guide is windows specific in places
you will need node.js follow the tiddlywiki guide for details

Plugins

This actually required two plugins. One helper that exists within your tiddlwyiki, and another export plugin you use in a Wikifolder

Helper

https://github.com/welford/twstaticblog/tree/master/helper

Locally available here : $:/plugins/welford/twstaticblog/helper

Exists within your Tiddlywiki and lets you customise the blog's output without having to worry about the format of your own wiki changing. By editing the tiddlers in this plugin you can change the name of the blog, which tags define your blog, how posts are linked to, and several other things.

Exporter

https://github.com/welford/twstaticblog/tree/master/export: Invoked when exporting the blog, this plugin swaps out some of the core view template tiddlers for those in the helper and as such should not be imported into your own TW. It also contains the templates used when constructing each type of page (The types, discussed below, are Blog Post, Index, Framework, and Tag)

Helper Details

Configuration

All the tags listed below are fully customizable:

plugin tiddler	purpose
`$:/plugins/welford/twstaticblog/helper/ctrl.post`	Defines which tags constitutes a blog post, defaults to blog
`$:/plugins/welford/twstaticblog/helper/ctrl.framework`	Defines which tags constitutes a blog framework blog-framework
`$:/plugins/welford/twstaticblog/helper/ctrl.donotexport`	Defines which tags should not be exported even if they are tagged as a blog posts or blog frameworks blog-donotexport blog-draft
`$:/plugins/welford/twstaticblog/helper/ctrl.donotindex`	Defines which tags will filtered from the index post unindex
`$:/plugins/welford/twstaticblog/helper/ctrl.hidden`	Defines which tags will be excluded from tag posts and from the tag lists below the title of artiles. blog blog-donotexport blog-draft blog-framework unindex

ctrl.post

Tag any article blog and it will be exported as part of your blog using the templater $:/plugins/welford/twstaticblog/helper/template.post.html . The output directory will be ./YYYY/MM/DD/[tiddlername].html based on their creation date of the article.

You can change the tags which define a blog post via $:/plugins/welford/twstaticblog/helper/blogentrytags

e.g. This post you are reading

template.index.html

Any recently created article tagged with blog will be included in index.html using the $:/plugins/welford/twstaticblog/helper/template.index.html. This can be prevented by also adding the tag unindex

e.g. the exported index.html

Framework

Tag any article blog-framework and it will be exported as part of your blog as a "framework" post using the template $:/plugins/welford/twstaticblog/helper/template.framework.html. The output location in the root directory. I define a framework article as being a post which helps you navigate the site or one that is accessabe everywhere. I have included a few example framework posts in the helper plugin.

e.g. Tags, About both linked to at the top of this page

Tag

As this is a static site generator there is no search functionaity. My plugin auto-generates tag posts, using the template $:/plugins/welford/twstaticblog/helper/template.tag.html, based on any tag in blog or framework posts as a kind of simple site-map. You can exclude tags from being included in this by adding them to the tag list in $:/plugins/welford/twstaticblog/helper/hiddentags

By default the following are excluded:

e.g. example random unique tag <- you can click on these and jump to specified tag page.

Static Bannner

A banner can be added to the top of every page via $:/plugins/welford/twstaticblog/helper/blog-banner in my case I use it to link to some of the framework posts.

Export Static Blog

2021/4/6 20:58

Install Node.js and Tiddlywiki

follow the guide : https://tiddlywiki.com/#GettingStarted%20-%20Node.js

Example Batch File

see https://github.com/welford/twstaticblog/tree/master/example/export-basic.bat

rd .\temp\blog-basic /s /q
call tiddlywiki --load .\example.html --savewikifolder .\temp\blog-basic
XCOPY /E /I /Y .\tw-basic .\temp\blog-basic
call tiddlywiki .\temp\blog-basic --output .\blog-basic --build css
call tiddlywiki .\temp\blog-basic --output .\blog-basic --build framework
call tiddlywiki .\temp\blog-basic --output .\blog-basic --build tag
call tiddlywiki .\temp\blog-basic --output .\blog-basic --build posts
call tiddlywiki .\temp\blog-basic --output .\blog-basic --build index
rd .\temp\blog-basic /s /q

Delete ./temp/blog-basic incase it is not empty
Export the local tiddlywiki, in this case example.html, as a wikifolder to ./temp/blog-basic
1. see https://tiddlywiki.com/#TiddlyWikiFolders for full details
copy ./tw-basic/ folder to ./temp/blog-basic
1. This lets us override any settings in the original exported wiki
2. Crucially it contains the export part of the plugin
Load the temp wiki folder and export css to .\blog-basic
Load the temp wiki folder and export framework pages to .\blog-basic
Load the temp wiki folder and export tag pages to .\blog-basic
Load the temp wiki folder and export posts pages to .\blog-basic
Load the temp wiki folder and export index pages to .\blog-basic
delete ./temp/blog-basic

Styled Example

see https://github.com/welford/twstaticblog/tree/master/example/export-styled.bat

exports temp to .\temp\blog-styled and final data to .\blog-styled

uses .\tw-styled to override the tyles in this wiki

highlight example

2021/4/6 20:46

Javascript code:

(function(a,b){
    var result = a+b;
    return result;
})(10,20)

CSS code:

 * { margin: 0; padding: 0; } /* micro reset */

html { font-size: 62.5%; }
body { font-size: 14px; font-size: 1.4rem; } /* =14px */
h1   { font-size: 24px; font-size: 2.4rem; } /* =24px */

Perl code:

package Name;
my $singleton;

BEGIN {
    $singleton = {
        attribute => 'value',
        another   => 'something',
    };
    bless $singleton, "Name";
}

sub new {
    my $class = shift;
    return $singleton;
}

Python code:

class Singleton:
    __single = None
    def __init__( self ):
        if Singleton.__single:
            raise Singleton.__single
        Singleton.__single = self

Tips

2021/4/6 19:40

Change Exported Style

You can keep your personal tiddlywiki in one format and have the exported blog in another. In the tw\tiddlers\keep a file called $__theme.tid containing the name of the style you wish to use e.g. using $:/themes/welford/phasersonkill-static

created: 20150620130427249
modified: 20151207212411514
title: $:/theme
type: text/vnd.tiddlywiki

$:/themes/welford/phasersonkill-static

Any style you use will need to be included in your personal tiddlywiki or as a plugin in the tw/plugins folder. It's probably easier to have it contained within your own tiddlywiki but not as the active theme.

See https://github.com/welford/twstaticblog/tree/master/example/export-styled.bat

Change Exported Palette

Same as above, but using a file called $__palette.tid:

created: 20170408201459621
modified: 20170408201500717
title: $:/palette
type: text/vnd.tiddlywiki

$:/palettes/welford/phasersonkill

See https://github.com/welford/twstaticblog/tree/master/example/export-styled.bat

A Long Example Blog

2017/4/16 19:14

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur porttitor pharetra lacus nec blandit. Vivamus non augue posuere est sodales aliquet ultricies vel metus. Suspendisse potenti. Nullam nec nibh lacinia, scelerisque mauris sollicitudin, molestie urna. Nullam congue pharetra condimentum. Praesent eget iaculis tellus, et iaculis velit. Etiam vel rhoncus nulla. Morbi volutpat felis sem, non pretium ante mollis nec. Mauris vitae dui at magna pellentesque tincidunt nec vel justo. Etiam mi ex, suscipit eu scelerisque quis, mattis non augue. Sed at felis ac quam luctus vehicula. Fusce et pellentesque turpis. In a pretium orci. Morbi tempor sodales sodales.

Suspendisse potenti. Nunc vitae purus sit amet metus ornare aliquet. Nunc erat risus, interdum nec est ut, placerat vehicula turpis. Vestibulum a metus et erat scelerisque consectetur. Duis volutpat placerat est auctor finibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum porta dui ut neque laoreet varius. Maecenas porta nec lacus eget bibendum. Cras sed scelerisque eros, at pulvinar nibh. Sed ullamcorper tortor hendrerit est scelerisque, nec finibus mi cursus. Maecenas sodales quam erat, ac fringilla lorem congue sit amet. Sed sem sapien, rhoncus vel porttitor ac, sagittis sit amet dui. Nunc mollis, est eu vulputate sodales, massa nisl faucibus enim, eget elementum est lorem in mauris.

Morbi congue semper neque, quis pulvinar nisi interdum quis. Mauris risus ipsum, elementum a tincidunt non, rhoncus et lacus. Vivamus sit amet rutrum nibh. Cras ut faucibus mauris. Morbi imperdiet condimentum massa et interdum. In gravida velit ut odio venenatis, sit amet sollicitudin felis gravida. Cras egestas nisi vel rutrum auctor.

Maecenas et iaculis tellus. Nunc fringilla in mauris nec tincidunt. Mauris vehicula rhoncus vestibulum. Fusce porta leo nulla, at blandit nibh condimentum vel. Vivamus nec est a purus dictum varius quis a nibh. Sed tellus metus, eleifend quis accumsan euismod, mattis in metus. Aliquam consectetur felis a iaculis porttitor. Integer ac diam enim. Morbi luctus libero placerat odio placerat rutrum. Integer vestibulum aliquet metus.

Vivamus vel scelerisque tellus. Etiam aliquet, nibh id lobortis aliquet, mauris sapien volutpat odio, nec hendrerit massa ipsum viverra nunc. Praesent blandit, elit ultrices pretium auctor, risus massa fringilla arcu, in porttitor lorem neque in arcu. Mauris et nisl quis nunc cursus pharetra. Quisque interdum, risus in consectetur mollis, ex tellus pulvinar magna, ut dictum lorem eros quis justo. Sed eu rutrum dui. Aliquam elementum luctus laoreet. Curabitur a augue finibus eros ornare rutrum.