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 %}
|
||||
{% include path %}
|
||||
{% endset %}
|
||||
{{ code | replace(" ", "•") }}
|
||||
{{ code | safe | replace(" ", "•") }}
|
||||
```
|
||||
{% 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`))
|
||||
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