Basic documentation written.
This commit is contained in:
parent
0f3acaf7c2
commit
d4e616bc54
7
content/code/example_config.json
Normal file
7
content/code/example_config.json
Normal file
|
@ -0,0 +1,7 @@
|
||||||
|
{
|
||||||
|
"contentDir": "content",
|
||||||
|
"assetsDir": "assets",
|
||||||
|
|
||||||
|
"serverPort": "8789",
|
||||||
|
"serverName": "qwik"
|
||||||
|
}
|
|
@ -3,6 +3,6 @@
|
||||||
{% set code %}
|
{% set code %}
|
||||||
{% include path %}
|
{% include path %}
|
||||||
{% endset %}
|
{% endset %}
|
||||||
{{ code | replace(" ", "•") }}
|
{{ code | safe | replace(" ", "•") }}
|
||||||
```
|
```
|
||||||
{% endmacro %}
|
{% endmacro %}
|
101
content/pages/docs/intro.njk
Normal file
101
content/pages/docs/intro.njk
Normal 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 %}
|
|
@ -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 %}
|
|
|
@ -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 %}
|
|
|
@ -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`))
|
||||||
}
|
}
|
Loading…
Reference in New Issue
Block a user