101 lines
4.0 KiB
Plaintext
101 lines
4.0 KiB
Plaintext
|
{% extends "templates/article_md.njk" %}
|
||
|
|
{% import "components/code.njk" as code with context %}
|
||
|
|
|
||
|
|
{% block head %}
|
||
|
|
<title>qwik cms - intro </title>
|
||
|
|
{% endblock %}
|
||
|
|
|
||
|
|
{% block header %}
|
||
|
|
qwik cms - docs
|
||
|
|
{% endblock %}
|
||
|
|
|
||
|
|
{% block main %}
|
||
|
|
# 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 (although with a caveat as of now)
|
||
|
|
|
||
|
|
|
||
|
|
## 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:
|
||
|
|
{{ code.import("code/example_config.json", "json") }}
|
||
|
|
|
||
|
|
## 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
|
||
|
|
Ow damn. I need to write this don't I? It will come later it's 00:30, and I am not feeling like writing
|
||
|
|
more now... But I could advise looking through the [nunjacks documentation](https://mozilla.github.io/nunjucks/)
|
||
|
|
and that could probably get you going a bit. Also, if you dare read the source code of the `content`-folder,
|
||
|
|
you could probably figure out how stuf works as well.
|
||
|
|
|
||
|
|
{% endblock %}
|