qwik-cms/content/pages/docs/intro.njk

{% 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

{% endblock %}