qwik-cms/content/pages/docs/intro.md

%%-
title: qwik cms
header: qwik cms intro
date: 8th August 2021
-%%

# Introduction
BurnyLlama started working on this project as a part of [qwik](https://qwik.space).
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:
1. Normal HTML
2. Nunjacks (an HTML templating language)
3. 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:
```bash
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:
```json
{
    "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`

# Usage