Introduction

BurnyLlama started working on this project as a part of qwik. We tried to find a good and simple CMS solution, but we couldn't really find something that worked for and suited us. We decided to make our own, and that's when the qwik-cms repo was created.

Basic ideas

We wanted to keep it simple, yet powerful. At first we only wanted to use include/import statements, but later we came to the realization that you could add other QoL things, like automatically generating a table of contents for articles.

We also want to make development of content be as fast as possible. Especially with when it comes to writing articles. Writing articles in markdown can feel kinda nice as it (at least imo) saves a lot of time compared to writing out HTML.

Underlying technologies

Thanks to all the technologies used, the CMS is really hackable and can be used in different ways depending on your liking. There are three main ways of creating content:

Normal HTML
Nunjacks (an HTML templating language)
Markdown

Views on bloat

This all sounds kinda bloated? I hear you asking... and yes, I am afraid this is a bit bloated (sadly). Although I wouldn't call it bloated if you actually use the features. The project does pull in a few dependencies, and making the system more modular could potentially make som of those dependencies optional, but as of now we depend on:

Express - the server framework
nunjucks - the templating language that does very heavy lifting in this CMS.
nunjucks-markdown - adds support for markdown in nunjucks
marked - the actual renderer for the markdown (used by nunjucks-markdown)
highlight.js - provides syntax highlighting for codeblocks in markdown.
jsdom - makes us able to use DOM operations server-side (used to generate the table of contents)
chokidar - used to reload nunjucks templates if they change on the disk (without having to restart the server)

So yes, we sure do have a lot of dependencies, but they are all used, so there are no dependencies just "lying around".

Installation

The installation process will be quite trivial if you are used to node-based projects.

Prerequesites

We will assume that you have node and npm installed already. Otherwise make sure to install those.

Process

The process is really simple:

git clone https://git.qwik.space/BurnyLlama/qwik-cms
cd qwik-cms
npm i
node index.js

npm i installs all needed dependencies.

Configuration

The CMS can be configured from config.json and the default config looks like this:

{
    "contentDir": "content",
    "assetsDir": "assets",

    "serverPort": "8789",
    "serverName": "qwik"
}

Explanation

All of the options are kind of self-explanatory, but anyways:

contentDir

Specifies which directory the content is in.

Default: content

assetsDir

Specifies which directory the assets are in. These items will be statically available on (your site's) /assets/. I recommend storing CSS, images, etc. here.

Default: assets

serverPort

The port the server should run on.

Default: 8789

serverName

This can be accessed in any page/template by using {{ serverName }}

Default: qwik

3.2 KiB Raw Blame History