Installation

As of time of writing this post, Writerside is available for free as a both standalone application and a plugin for JetBrains IDEs. Since I'm already using their IDEs, I will be using plugin version. It doesn't look like Writerside is installing or requiring any additional dependencies for now. And that's seems like about it for installation. Pretty simple compared to Pelican where pipx (or at least Python installation) is required to get started.

Create site

To start with I will be creating new Writerside project. Plugin comes with tool window:

Creating new Writerside project creates one with default Help instance and This is the first topic entry, which gives a glimpse of what Writerside is capable of. First thing I'm changing is Help instance to Blog because that's what I'm trying to achieve here.

Moving on, let's try to create first few dummy posts to see how site structure looks like and to what extent it is customisable. And that's where first roadblock is. I can't really create entries without them appearing in the table of contents, which means that every post I create needs to be visible on site menu. First thing I'm trying to do to work around this is to create yearly topics and put posts in them. That way I can at least hide posts from top-level menu. It doesn't look like I can do anything more than that. It can change in the future if/when Writerside will support themes, but that would move a lot of logic into theme and I'm not sure if that's the desirable outcome. For what it's worth, it was not intended to be a bloging engine in the first place.

Next thing is to have home page for the blog. And there comes yet another roadblock. I can't really create "dynamic" page (that will be rebuilt on every content change) that will be used as home page. I can create static page, manually add links to other topics acting as blog posts, but that's not really how it should be done - too many moving parts to keep in sync. Also I didn't try to create such page using summary from linked topics, but I'm not sure if that is even possible at the moment. Yeah, this is really not a blogging engine for sure. And it seems like the only intended use case is creating help docs and nothing more - every page visible in the table of contents acting as menu for whole site, theme working very well as a help docs theme, and other minor details that adds up to Writerside being very good tool for creating help docs. Or API documentation, although API Platform I'm using for my projects is building better API documentation in my opinion.

Writing content on Writerside is nothing different from writing content in any other markup language/tool if we're talking about simple things: some headers, some bolds, some italics, simple things. But if you want to go extra, Writerside got you covered - code snippets with different language in different tab, pro tip boxes, notes, warnings - whatever you want. And if that is not enough, it is always possible to go almost raw HTML. Great example is their own docs for Writerside written by what I assume is Writerside itself (same theme, same site structure).

What I'm missing at the moment is theming support. It's not really possible to build something that would fall right into some existing website. I mean if I had website themed in some particular way, and would like to have similar feel in help section (for whatever reason), the most I can do now is set primary color for help docs site, add logo, and add links/text to footer. And that's about all I could do. Although I must notice that current theme is very good - it has light/dark themes, table of contents for particular topic, search, and other small things.

Build site

Publishing couldn't get any simpler - click Generate website, select whether you want to preview it in browser or have zip archive created with everything necessary for deployment and that's it. Site structure looks pretty lean and light:

$ tree output
output
├── HelpTOC.json
├── Map.jhm
├── config.json
├── current.help.version
├── images
│   ├── completion_procedure.png
│   ├── completion_procedure_dark.png
│   ├── convert_table_to_xml.png
│   ├── convert_table_to_xml_dark.png
│   ├── new_topic_options.png
│   └── new_topic_options_dark.png
├── index.html
├── mermaid.css
├── resources
└── starter.html

It is much simpler than Pelican's output, but that's because it doesn't really need to support different themes, so it could be optimised to the max.

Is it good?

Overall I think that Writerside doesn't introduce anything groundbreaking, but what it does is it comes with nice GUI, default theme that works great for help docs, and is easy to use - click publish, give zip to devops to deploy, or just trigger pipeline on push to repo. I don't imagine switching to it if I'm using something with similar styling capabilities now, but I would be really keen to use it if I would be starting from scratch - Writerside makes it easier to start. Only thing that would be a bummer is that to fully utilise it, I would need to write at least some of content in semantic markup.