qwik-cms/README.md

106 lines
3.1 KiB
Markdown
Raw Normal View History

2021-07-27 21:47:00 +02:00
# qwik cms
2021-07-27 16:56:40 +02:00
2021-07-27 21:47:00 +02:00
This is a **really** basic CMS. But it will get the job done. It basically operates really simple.
It checks what path a client is trying to access and checks if there is a corresponding file for
that. After that it renders the file if it exists (if not it sends a 404 error).
## Installation
### Requirements:
* node
* npm
### Instructions:
```bash
git clone https://git.qwik.space/BurnyLlama/qwik-cms
cd qwik-cms
npm i
node index.js
```
### Extra info
Even tho it can be annoying, I would recommend looking through what code this will run on your
PC/server. Otherwise you would have to take my word for it, which could be a bad idea. (Although
I can *promise* you that there is no malicious code or dependency in this project AFAIK.)
The project depends on the following packages (installed when you ran `npm i`):
* express (a web server framework)
* nunjucks (a templating engine)
2021-08-04 20:08:16 +02:00
* nunjucks-markdown (markdown support in nunjucks)
* marked (markdown parser/compiler)
2021-08-04 22:52:49 +02:00
* highlight.js (syntax highlighting)
* jsdom (an extension that can use the DOM server-side - used to render the ToC)
2021-07-27 21:57:48 +02:00
* chokidar (reload templates if they change on disk)
2021-07-27 21:47:00 +02:00
* fs (used for filesystem operations)
### Maintenence
I recommend forking (or just cloning) this repository if you want a long-term solution for stuff like
multiple people working on the site.
## How do I create pages?
Let's say you want a page on the path `/foo`, then you can create the corresponding file in two places:
* `{contentDir}/pages/foo.njk`
* `{contentDir}/pages/foo/index.njk`
`/foo/bar` would be in either of:
* `{contentDir}/pages/foo/bar.njk`
* `{contentDir}/pages/foo/bar/index.njk`
If both files exist the first one specified is rendered. `{contentDir}` is configured in `config.json` and its default is `content/`.
The documents are written in the [nunjucks](https://mozilla.github.io/nunjucks/) templating language
which means you can use imports/includes/etc for code reusability.
## Configuration
The default configuration looks like this:
```json
{
"contentDir": "content",
"assetsDir": "assets",
"serverPort": "8789",
"serverName": "qwik"
}
```
The file is called `config.json`.
### Descriptions
#### 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`
## Future features
I have some ideas on things that would be good to implement, one of which is plugins/extensions that
can provide extra functionality.
As an example, it would be cool to be able to implement sidebars that
contains all pages (if you're making a blog or wiki/documentation).
It would also be nice to have a plugin that could auto update (and restart) the server if you make
changes to a git repository. (You could do this with cronjobs in theory, but this *should* be the
server's responsibility.)