Basic documentation written.

This commit is contained in:
BurnyLlama 2021-08-06 00:33:58 +02:00
parent 0f3acaf7c2
commit d4e616bc54
6 changed files with 110 additions and 43 deletions

View File

@ -0,0 +1,7 @@
{
"contentDir": "content",
"assetsDir": "assets",
"serverPort": "8789",
"serverName": "qwik"
}

View File

@ -3,6 +3,6 @@
{% set code %} {% set code %}
{% include path %} {% include path %}
{% endset %} {% endset %}
{{ code | replace(" ", "•") }} {{ code | safe | replace(" ", "•") }}
``` ```
{% endmacro %} {% endmacro %}

View File

@ -0,0 +1,101 @@
{% 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 %}

View File

@ -1,25 +0,0 @@
{% extends "templates/article.njk" %}
{% import "components/toc.njk" as toc with context %}
{% block head %}
<title>qwik cms - docs - main</title>
{% endblock %}
{% block header %}
qwik cms - docs
{% endblock %}
{% block main %}
{{ toc.header("h1", "Basic idea") }}
<p>
Our CMS can be used in multiple (different) ways thanks to the underlying technologies.
The basic idea is that every page is a file. Although how you treat that file is really
up to you. It can be plain HTML, nunjucks/njk (a templating language for HTML) or even
markdown (although not "plain markdown").
</p>
{{ toc.header("h2", "Views on bloat") }}
<p>
I do not want to bloat this CMS, but I must admit that it is bloated.
{{ hello }}
</p>
{% endblock %}

View File

@ -1,16 +0,0 @@
{% extends "templates/article_md.njk" %}
{% block head %}
<title>qwik cms - docs - main</title>
{% endblock %}
{% block header %}
qwik cms - docs
{% endblock %}
{% block main %}
# Test
Heyyy you there!
## Undertest
{% endblock %}

View File

@ -8,5 +8,5 @@ export function requestHandler(req, res, Config) {
if (fs.existsSync(`./${Config.contentDir}/pages/${req.path}/index.njk`)) if (fs.existsSync(`./${Config.contentDir}/pages/${req.path}/index.njk`))
return res.send(njkRenderer(`./${Config.contentDir}/pages/${req.path}/index.njk`)) return res.send(njkRenderer(`./${Config.contentDir}/pages/${req.path}/index.njk`))
return res.status(404).render('errors/404.njk', context) return res.status(404).send(njkRenderer(`./${Config.contentDir}/errors/404.njk`))
} }