Convos as a document and blogging service

Posted by Jan Henning Thorsen on 3. Jun, 2020.

A CMS in Convos? Why? How..? https://convos.chat used to be powered by GitHub Pages, but it is now powered by "Convos Pages" instead. The CMS support was mainly added to make it easier to maintain our web page, but can be used by anyone as a generic CMS.

Last week we also changed the domain name from convos.by to "convos.chat". We did the switch because the ".by" domain raised questions by our users and was hard to remember.

The result is a new and shiny webpage that reflects the main Convos design rules!

How to create your own content

The custom web page can be created by creating some directories and files in $CONVOS_HOME.

$CONVOS_HOME/content/index.md will override the index page (/) of your Convos installation. "/" does normally just redirect to /login or /chat, so overriding this page is completely fine.
Any file that ends with ".md" in the $CONVOS_HOME/content/doc/ directory will be available under the /doc path. A special "index.md" file will be served directly from /doc path.
Blog entries must be created in the "blog" directory with the format $CONVOS_HOME/content/blog/$YEAR/$YEAR-$MON-$MDAY-$TITLE.md. Example $CONVOS_HOME/content/blog/2020/2020-06-03-content-management-system.md.
Any static file, such as images, can be placed in the $CONVOS_HOME/content/public/ directory. Do be careful though, and avoid override any core Convos files.
Files in the $CONVOS_HOME/content/templates/ directory can be used to add, or override any core Convos template. Supported overrides are the templates/partial/cms*.ep files.

See the www.convos.chat branch for a working example, being this web site.

git clone https://github.com/convos-chat/convos.git \
  -b www.convos.chat ~/.local/share/convos/content

Supported markdown

The markdown files support the basic Markdown syntax through the Text::Markdown parser. In additon it supports the following...

Headings

Headings will have the "id" attribute, which is as slug of the text inside the heading. The headings will also be available to be displayed as a "table of content" under the first heading. See Supported YAML front-matter for how to display the TOC.

Markdown inside block tags


  ### Some header

      document.querySelector('#code-example');

The content inside a block tag with the "markdown" attribute will be stripped of the whitespace of the first line, before being run through the markdown parser. This will make it a lot easier to indent the markdown correctly and read the markup.

Styling

FontAwesome icons

![fab](github) = 
![fas](eye)    =

Two special image formats will be turned into FontAwesome icons instead.

"fas" icons is in the "Solid" category.
"fab" icons is in the "Brands" category.
The img url will be prefixed with "fa-" to make up the final class name.

Supported YAML front-matter

The YAML front-matter can be used to give extra rendering instructions. Example front-matter:

---
title: Some document title
description: Some cool description
image: /some/picture.jpg
toc: true
canonical: https://example.com/source/url
redirect_to: /something/else.html
---

"title" will be used as document title.
"description" will be used as meta, facebook and twitter description. If no description is provided, then the first paragraph found in the document will be used.
"image" can be used to set a custom image that will be displayed when the document is displayed on social media, or inside Convos.
"toc" will cause a "table of content" to be displayed under the main header.
"canonical" can be set to point to the original source of this conent.
"redirect_to" will override any other setting and cause a redirect from this URL to another relative or absolute URL.

Automatic content

Any Perl document available on the system can also be rendered under the "/doc" path. This feature is currently experimental: The URL might change in the future, in case it causes too many collisions. This feature must however be enabled with an environment variable:

CONVOS_CMS_PERLDOC=1 ./script/convos daemon

What is next?

It is unlikely to make a WYSIWYG editor for Convos, but if you like this addition then we would probably take a PR. Like this additon, but don't want all of Convos? Convos::Plugin::Cms should be fairly easy to pull out and embed in your own Mojolicious project.

So what is next? Check out our milestones or give us a nuge or comment on the issues.

Want to help out with the project? Have a look at the developement guide or come talk to us in the #convos channel on irc.libera.chat:6697.