From d4e616bc540d5a137677ac2390fcebfaa8160ff1 Mon Sep 17 00:00:00 2001 From: BurnyLlama Date: Fri, 6 Aug 2021 00:33:58 +0200 Subject: [PATCH] Basic documentation written. --- content/code/example_config.json | 7 +++ content/components/code.njk | 2 +- content/pages/docs/intro.njk | 101 +++++++++++++++++++++++++++++++ content/pages/docs/main.njk | 25 -------- content/pages/docs/main_md.njk | 16 ----- libs/requestHandler.js | 2 +- 6 files changed, 110 insertions(+), 43 deletions(-) create mode 100644 content/code/example_config.json create mode 100644 content/pages/docs/intro.njk delete mode 100644 content/pages/docs/main.njk delete mode 100644 content/pages/docs/main_md.njk diff --git a/content/code/example_config.json b/content/code/example_config.json new file mode 100644 index 0000000..2ef460a --- /dev/null +++ b/content/code/example_config.json @@ -0,0 +1,7 @@ +{ + "contentDir": "content", + "assetsDir": "assets", + + "serverPort": "8789", + "serverName": "qwik" +} \ No newline at end of file diff --git a/content/components/code.njk b/content/components/code.njk index 9ff1783..495f139 100644 --- a/content/components/code.njk +++ b/content/components/code.njk @@ -3,6 +3,6 @@ {% set code %} {% include path %} {% endset %} -{{ code | replace(" ", "•") }} +{{ code | safe | replace(" ", "•") }} ``` {% endmacro %} \ No newline at end of file diff --git a/content/pages/docs/intro.njk b/content/pages/docs/intro.njk new file mode 100644 index 0000000..7de61a4 --- /dev/null +++ b/content/pages/docs/intro.njk @@ -0,0 +1,101 @@ +{% extends "templates/article_md.njk" %} +{% import "components/code.njk" as code with context %} + +{% block head %} + qwik cms - intro +{% 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 %} \ No newline at end of file diff --git a/content/pages/docs/main.njk b/content/pages/docs/main.njk deleted file mode 100644 index acda156..0000000 --- a/content/pages/docs/main.njk +++ /dev/null @@ -1,25 +0,0 @@ -{% extends "templates/article.njk" %} -{% import "components/toc.njk" as toc with context %} - -{% block head %} - qwik cms - docs - main -{% endblock %} - -{% block header %} - qwik cms - docs -{% endblock %} - -{% block main %} - {{ toc.header("h1", "Basic idea") }} -

- 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"). -

- {{ toc.header("h2", "Views on bloat") }} -

- I do not want to bloat this CMS, but I must admit that it is bloated. - {{ hello }} -

-{% endblock %} \ No newline at end of file diff --git a/content/pages/docs/main_md.njk b/content/pages/docs/main_md.njk deleted file mode 100644 index 77eba6f..0000000 --- a/content/pages/docs/main_md.njk +++ /dev/null @@ -1,16 +0,0 @@ -{% extends "templates/article_md.njk" %} - -{% block head %} - qwik cms - docs - main -{% endblock %} - -{% block header %} - qwik cms - docs -{% endblock %} - -{% block main %} - # Test - Heyyy you there! - - ## Undertest -{% endblock %} \ No newline at end of file diff --git a/libs/requestHandler.js b/libs/requestHandler.js index 287aef8..cc899de 100644 --- a/libs/requestHandler.js +++ b/libs/requestHandler.js @@ -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`)) } \ No newline at end of file