Convos as a document and blogging service
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.chat 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.mdwill 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
The markdown files support the basic Markdown syntax through the Text::Markdown parser. In additon it supports the following...
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
<div markdown> ### Some header document.querySelector('#code-example'); </div>
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.
<style> tags will be merged and moved into <head>.
![fab](github) = <i class="fab fa-github"/> ![fas](eye) = <i class="fas fa-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.
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.