Technology Tales

Moves to Hugo

What amazes me is how things can become more complicated over time. As long as you knew HTML, CSS and JavaScript, building a website was not as onerous as long as web browsers played ball with it. Since then, things have got easier to use but more complex at the same time. One example is WordPress: in the early days, themes were much simpler than they are now. The web also has got more insecure over time, and that adds to complexity as well. It sometimes feels as if there is a choice to make between ease of use and simplicity.

It is against that background that I reassessed the technology that I was using on my public transport and Irish history websites. The former used WordPress, while the latter used Drupal. The irony was that the simpler website was using the more complex platform, so the act of going simpler probably was not before time. Alternatives to WordPress were being surveyed for the first of the pair, but none had quite the flexibility, pervasiveness and ease of use that WordPress offers.

There is another approach that has been gaining notice recently. One part of this is the use of Markdown for web publishing. This is a simple and distraction-free plain text format that can be transformed into something more readable. It sees usage in blogs hosted on GitHub, but also facilitates the generation of static websites. The clutter is absent for those who have no need of the Gutenberg Editor on WordPress.

With the content written in Markdown, it can be fed to a static website generator like Hugo. Using defined templates and fixed assets like CSS together with images and other static files, it can slot the content into HTML files very speedily since it is written in the Go programming language. Once you get acclimatised, there are no folder structures that cannot be used, so you get full flexibility in how you build out your website. Sitemaps and RSS feeds can be built at the same time, both using the same input as the HTML files.

In a nutshell, it automates what once needed manual effort used a code editor or a visual web page editor. The use of HTML snippets and layouts means that there is no necessity for hand-coding content, like there was at the start of the web. It also helps that Bootstrap can be built in using Node, so that gives a basis for any styling. Then, SCSS can take care of things, giving even more automation.

Given that there is no database involved in any of this, the required information has to be stored somewhere, and neither the Markdown content nor the layout files contain all that is needed. The main site configuration is defined in a single TOML file, and you can have a single one of these for every publishing destination; I have development and production servers, which makes this a very handy feature. Otherwise, every Markdown file needs a YAML header where titles, template references, publishing status and other similar information gets defined. The layouts then are linked to their components, and control logic and other advanced functionality can be added too.

Because static files are being created, it does mean that site searching and commenting or contact pages cannot work they would on a dynamic web platform. Often, external services are plugged in using JavaScript. One that I use for contact forms is Getform.io. Then, Zapier has had its uses in using the RSS feed to tweet site updates on Twitter when new content gets added. Though I made different choices, Disqus can be used for comments and Algolia for site searching. Generally, though, you can find yourself needing to pay, particularly if you need to remove advertising or gain advanced features.

Some comments service providers offer open source self-hosted options, but I found these difficult to set up and ended up not offering commenting at all. That was after I tried out Cactus Comments only to find that it was not discriminating between pages, so it showed the same comments everywhere. There are numerous alternatives like Remark42, Hyvor Talk, Commento, FastComments, Utterances, Isso, Mouthful, Muut and HyperComments but trying them all out was too time-consuming for what commenting was worth to me. It also explains why some static websites even send readers to Twitter if they have something to say, though I have not followed this way of working.

For searching, I added a JavaScript/JSON self-hosted component to the transport website, and it works well. However, it adds to the size of what a browser needs to download. That is not a major issue for desktop browsers, but the situation with mobile browsers is such that it has a sizeable effect. Testing with PageSpeed and Lighthouse highlighted this, even if I left things as they are. The solution works well in any case.

One thing that I have yet to work out is how to edit or add content while away from home. Editing files using an SSH connection is as much a possibility as setting up a Hugo publishing setup on a laptop. After that, there is the question of using a tablet or phone, since content management systems make everything web based. These are points that I have yet to explore.

As is natural with a code-based solution, there is a learning curve with Hugo. Reading a book provided some orientation, and looking on the web resolved many conundrums. There is good documentation on the project website, while forum discussions turn up on many a web search. Following any research, there was next to nothing that could not be done in some way.

Migration of content takes some forethought and took quite a bit of time, though there was an opportunity to carry some housekeeping as well. The history website was small, so copying and pasting sufficed. For the transport website, I used Python to convert what was on the database into Markdown files before refining the result. That provided some automation, but left a lot of work to be done afterwards.

The results were satisfactory, and I like the associated simplicity and efficiency. That Hugo works so fast means that it can handle large websites, so it is scalable. The new Markdown method for content production is not problematical so far apart from the need to make it more portable, and it helps that I found a setup that works for me. This also avoids any potential dealbreakers that continued development of publishing platforms like WordPress or Drupal could bring. For the former, I hope to remain with the Classic Editor indefinitely, but now have another option in case things go too far.

Killing a hanging SSH session

My web hosting provider offers SSH access that I often use for such things as updating Matomo and Drupal together with more intensive file moving than an FTP session can support. However, I have found in recent months that I no longer can exit cleanly from such sessions using the exit command.

Because this produces a locked terminal session, I was keen to find an alternative to shutting down the terminal application before starting it again. Handily, there is a keyboard shortcut that does just what I need.

It varies a little according to the keyboard that you have. Essentially, it combines the carriage return key with ones for the tilde (~) and period (.) characters. The tilde may need to be produced by the combining the shift and backtick keys on some keyboard layouts but that is not needed on mine. So far, I have found that the <CR>+~+. combination does what I need until SSH sessions start exiting as expected.

Another look at Drupal

Early on in the first year of this blog, I got to investigating the use of Drupal for creating an article-based subsite. In the end, the complexities of its HTML and CSS thwarted my attempts to harmonise the appearance of web pages with other parts of the same site and I discontinued my efforts. In the end, it was Textpattern that suited my needs and I have stuck with that for the aforementioned subsite. However, I recently spotted someone very obviously using Drupal in its out of the box state for a sort of blog (there is even an extension for importing WXR files containing content from a WordPress blog); they even hadn’t removed the Drupal logo. With my interest rekindled, I took another look for the sake of seeing where things have gone in the last few years. Well, first impressions are that it now looks like a blogging tool with greater menu control and the facility to define custom content types. There are plenty of nice themes around too though that highlights an idiosyncrasy in the sense that content editing is not fully integrated into the administration area where I’d expect it to be. The consequence of this situation is that pages, posts (or story as the content type is called) or any content types that you have defined yourself are created and edited with the front page theme controlling the appearance of the user interface. It is made even more striking when you use a different theme for the administration screens. That oddity aside, there is a lot to recommend Drupal though I’d try setting up a standalone site with it rather than attempting to shoehorn it as a part of an existing one like what I was trying when I last looked.

Investigating Textpattern

With the profusion of Content Management Systems out there, open source and otherwise, my curiosity has been aroused for a while now. In fact, Automattic’s aspirations for WordPress (the engine powering this blog) now seem to go beyond blogging and include wider CMS-style usage. Some may even have put the thing to those kinds of uses but I am of the opinion that it has a way to go yet before it can put itself on a par with the likes of Drupal and Joomla!.

Speaking of Drupal, I decided to give it a go a while back and came away with the impression that it’s a platform for an entire website. At the time, I was attracted by the idea of having one part of a website on Drupal and another using WordPress but the complexity of the CSS in the Drupal template thwarted my efforts and I desisted. The heavy connection between template and back end cut down on the level of flexibility too. That mix of different platforms might seem odd in architectural terms but my main website also had a custom PHP/MySQL driven photo gallery too and migrating everything into Drupal wasn’t going to be something that I was planning. In hindsight, I might have been trying to get Drupal to perform a role for which it was never meant so I am not holding its non-fulfillment of my requirements against it. Drupal may have changed since I last looked at it but I decided to give an alternative a go regardless.

Towards the end of last year, I began to look at Textpattern (otherwise known as Txp) in the same vein and it worked well enough after a little effort that I was able to replace what was once a visitor dossier with a set of travel jottings. In some respects, Textpattern might feel less polished when you start to compare it with alternatives like WordPress or Drupal but the inherent flexibility of its design leaves a positive impression. In short, I was happy to see that it allowed me to achieve what I wanted to do.

If I remember correctly, Textpattern’s default configuration is that of a blog and it can be used for that purpose. So, I got in some content and started to morph the thing into what I had in mind. My ideas weren’t entirely developed so some of that was going on while I went about bending Txp to my will. Most of that involved tinkering in the Presentation part of the Txp interface though. It differs from WordPress in that the design information like (X)HTML templates and CSS are stored in the database rather than in the file system à la WP. Txp also has its own tag language called Textile and, though it contains conditional tags, I find that encasing PHP in <txp:php></txp:php> tags is a more succinct way of doing things; only pure PHP code can be used in this way and not a mixture of such in <?php ?> tags and (X)HTML. A look at the tool’s documentation together with perusal of Apress’ Textpattern Solutions got me going in this new world (it was thus for me, anyway). The mainstay of the template system is the Page and each Section can use a different Page. Each Page can share components and, in Txp, these get called Forms. These are included in a Page using Textile tags of the form <txp:output_form form=”form1″ />. Style information is edited in another section and you can have several style sheets too.

The Txp Presentation system is made up of Sections, Pages, Forms and Styles. The first of these might appear in the wrong place when being under the Content tab would seem more appropriate but the ability to attach different page templates to different sections places their configuration where you find it in Textpattern and the ability to show or hide sections might have something to do with it too. As it happens, I have used the same template for all bar the front page of the site and got it to display single or multiple articles as appropriate using the Category system. It may be a hack but it appears to work well in practice. Being able to make a page template work in the way that you require really offers a great amount of flexibility and I have gone with one sidebar rather than two as found in the default set up.

Txp also has facility to add plugins (look in the Admin section of the UI) and this is very different from WordPress in that installation involves the loading of an encoded text file, probably for sake of maintaining the security and integrity of your installation. I added the navigation facility for my sidebar and breadcrumb links in this manner and back end stuff like Tiny MCE editor and Akismet came as plugins too. There may not be as many of these for Textpattern but the ones that I found were enough to fulfill my needs. If there are plugin configuration pages in the administration interface, you will find these under the Extensions tab.

To get the content in, I went with the more laborious copy, paste and amend route. Given that I was coming from the plain PHP/XHTML way of doing things, the import functionality was never going to do much for me with its focus on Movable Type, WordPress, Blogger and b2. The fact that you only import content into a particular section may displease some too. Peculiarly, there is no easy facility for Textpattern to Textpattern apart from doing a MySQL database copy. Some alternatives to this were suggested but none seemed to work as well as the basic MySQL route. Tiny MCE made editing easier once I went and turned off Textile processing of the article text. This was done on a case by case basis because I didn’t want to have to deal with any unintended consequences arising from turning it off at a global level.

While on the subject of content, this is also the part of the interface where you manage files and graphics along with administering things like comments, categories and links (think blogroll from WordPress). Of these, it is the comment or link facilities that I don’t use and even have turned comments off in the Txp preferences. I use categories to bundle together similar articles for appearance on the same page and am getting to use the image and file management side of things as time goes on.

All in all, it seems to work well even if I wouldn’t recommend it to many to whom WordPress might be geared. My reason for saying that is because it is a technical tool and is used best if you are prepared to your hands dirtier from code cutting than other alternatives. I, for one, don’t mind that at all because working in that manner might actually suit me. Nevertheless, not all users of the system need to have the same level of knowledge or access and it is possible to set up users with different permissions to limit their exposure to the innards of the administration. In line with Textpattern’s being a publishing tool, you get roles such as Publisher (administrator in other platforms), Managing Editor, Copy Editor, Staff Writer, Freelancer, Designer and None. Those names may mean more to others but I have yet to check out what those access levels entail because I use it on a single user basis.

There may be omissions from Txp like graphical presentation of visitor statistics in place of the listings that are there now and the administration interface might do with a little polish but it does what I want from it and that makes those other considerations less important. That more cut down feel makes it that little more useful in my view and the fact that I have created A Wanderer’s Miscellany may help to prove the point. You might even care to take a look at it to see what can be done and I am sure that it isn’t even close to exhausting the talents of Textpattern. I can only hope that I have done justice to it in this post.

Technical considerations regarding the discussion aspect of blogging

When making a start in the world of blogging, there are so many things to consider that you almost need a trial run first to learn the lingo. In fact, getting up to speed by using a service like that offered by Blogger or WordPress.com seems a very sensible starting point. Even so, the business is like building a house in that you only really know what you are doing after you have done the deed and made all the mistakes. That is particularly true when you go down the self-administered blog route. For starters, it’s so easy to pick the wrong domain name or hosting provider. Selecting your blogging software is the next step, but that may not be so tricky; WordPress does a reasonable job and there’s always Movable Type, Expression Engine, Drupal (yes, really) or Habari.

That mention of blogging software brings me to something that I encountered recently: commenting functionality. I am coming around to the idea that this is probably something that needs to be considered up front because of the nature of blogging. After all, anyone who reads The Blog Herald regularly should be familiar with the idea of blogging conversations and that means that the technology to make it happen should be easy for visitors to use and easy for bloggers to administer. However, the two can collide. For one thing, there are a myriad of choices available to the blogger and the blight of comment spam is ever pervasive and growing.

When it comes to comment spam, it is best to realise that there are two sources of responses to a blog post: visitor comments or trackbacks (pingbacks?) from other blogs. I reckon that the latter is probably the channel where most of the detritus travels and various anti-spam solutions are on offer to curb its spread. Names from the WordPress world like Akismet, Spam Karma, Simple Trackback Validation and Bad Behaviour come to mind. The former can also be used, particularly when the unscrupulous make use of low-cost labour in low-cost countries, and that’s when the thorny questions of user registration and CAPTCHA‘s arise. There is something to be said for not going to extremes with these and just sticking with less onerous rules and filtering on the server side.

I must admit to having staggering into forcing visitors to register prior to adding a comment and then making them log in thereafter. I think that it’s for security reasons, but WordPress creates a password and then sends it to the person who is registering rather than displaying on a web page. That can create another problem: what happens if the email fails to arrive? In the last week, this has happened with a visitor to my hillwalking blog and there could be a number of reasons for the non-arrival of the relevant email. One is ironic: being an automated email, it gets stuck in the spam filters of the recipient’s mailbox and so never gets to them. It could also be a bug with WordPress itself (I have raised a ticket and I am awaiting what Automattic might have to say to it) or a consequence of some setting made by a hosting provider. All of that makes it hard to track down the cause of the issue but it kicks off other thoughts as to its resolution. One is to remove the needed for registration and logging in the first place, but there are third-party services that may help too. The former has turned out to be the case for this blog and it seems to be performing well enough so it is an acceptable option.

When it comes to using third-party comment handling systems, what needs to be considered is how well they work with your blog. For instance, I gave Disqus a quick whirl and soon realised that I needed to update the themes for my WordPress blogs if I were to use it on an ongoing basis. Otherwise, it worked fine but I was left wondering if it would have been better to have brought it in when I started a blog rather than part way through and with comments made using the existing WordPress functionality. There’s also Intense Debate and I am almost certain that there are more like it but I’ll be sticking with what WordPress offers for now. The theme for my hillwalking blog has been modified to allow prospective commenters to get in touch with me if they are having problems. That is only an interim approach while I consider what the way forward will be.

What about a book on WordPress development?

Here’s something that I would really appreciate: a book on code cutting for WordPress customisation and extension. Having the Codex is all very fine but having a dead tree compendium that you can peruse at your leisure is a definite bonus. If there was a way to get the Codex on PDF and print it all off for easier reading, that would be progress. I believe that a publisher did plan to bring to the market something like what I want but author and publisher parted company, a pity. It would be great to see something like Apress’ Pro Drupal Development for WordPress. What about it, Automattic folks?

Are developers and designers overcomplicating their CSS?

I have been tweaking the widgets in this blog and the thought has crossed my mind that purveyors of open source blogging and CMS’s may be overcomplicating matters with the CSS that they are writing. Using inheritance without much thought as to others having to pick it up is one irritation but bunching styles together can confuse too. For instance, you can draw from from two different styles for the same HTML element (it’s what’s going when you see class="class1 class2" in a tag definition), which is OK if done simply but can confuse matters when customisation is attempted later. Drupal particularly suffers from this bugbear but it’s their in WordPress too, though not to the same extent. Using a hierarchy to define and attach your styles (#id1 .class2 tag1 {style definition…} is the kind of thing that I have in mind), can also confound but I admit to finding the approach very useful for myself. I think that I know what’s driving this: the need to cut down the bulk of CSS files but using the advanced features that I mentioned above without clear commenting and other documentation hampers later efforts. It would be nice if every developer of a theme for use blogging or CMS software was forced to document their work extensively and share that documentation with interested users. After all, sharing is the whole purpose of their endeavours…

FCKeditor and Drupal

My Drupal investigation is currently in hiatus but I did get to exploring the world of modules and adding to the standard ones supplied. Drupal doesn’t have a WYSIWYG editor supplied in the standard package so I went and added one that I have used elsewhere: FCKeditor. Setting wasn’t much of a problem until I encountered the following error: Unknown element of UniversalKey panel. The solution to the problem is to remove the reference to UniversalKey from the configuration file fckeditor.config.js. It took a spot of finding so here it is for posterity and so that I’ll find again…

A web development toolbox

HTML Tidy for Windows

Drupal has modules (Import HTML and its helper Static HTML together make up one option) for importing static (X)HTML pages into its database and it needs HTML Tidy in order to work. Since I am playing with the thing on Windows, I went out and snagged the version for that OS. Being either lazy or bloody-minded, I tried an XHTML page with PHP code embedded in it and, needless to say, the thing choked. I must try it with plain XHTML instead.