Kuzzle Documentation

Our documentation is a statically generated website. The content is stored in a bunch of Markdown files built by VuePress.

Ok, but... Where is the actual content?

This is a meta repository, which means content is not here. The actual documentation is stored in the repositories of the different pieces of the Kuzzle ecosystem, e.g. the Kuzzle Core, the Javascript SDK, the GOLANG SDK and so on. And this is a good thing because documentation should live along with the code that it documents. So, what is this repository for?

This repository contains the following elements:

• the VuePress logic and plugins that convert a bunch of .md files into a multi-rooted single-page-application with server-side-rendering an all those cool features we love;
• the logic that gathers all the different documentations and organizes them in a set of different instances of VuePress;
• the CI configuration that allows GitHub Actions to build and deploy all those different VuePress instances on our hosting space.

We want to stress that each section of the documentation (Core, SDK JS, SDK GO, plugins, etc...) is built against a separate and independent instance of VuePress. All these pieces will be glued together by being hosted in the same S3 bucket but in different sibling directories.

If you want to edit the content, this is not the right place

This repository is essentially used to version the framework files and deploy the whole docs when necessary. In order to edit the content of the docs, please refer to the repositories that contain them.

I am working on the framework code and I want to see a preview

If you are working on the code of the documentation framework, this is the right place. And you want a preview of your work before pushing it to GitHub. For most operations of this kind, we use a CLI tool called kuzdoc.

If you haven't already done it, install Kuzdoc globally

npm install -g kuzdoc

:warning: You are not meant to run a local copy of the whole documentation. It is huge and it will take ages to build.

Then run

kuzdoc install --repo=sdk-javascript-7,kuzzle-2

This will only clone the sdk-javascript-7 and kuzzle-2 repos, choose the ones that you want to work on locally, trying to avoid having too many.

Note. If you don't remember exactly the name of the repo you want to install, you can omit the --repo option and just let kuzdoc show the list of the repo names.

Then you just need to run:

kuzdoc dev

I want to see a local preview of a static build of the whole documentation site

You might want to see how the whole docs look before merging stuff to master, so kuzdoc has the right command for you.

If you haven't already done it, install Kuzdoc and http-server globally

npm install -g kuzdoc http-server

If you haven't already done it, clone this repo somewhere

git clone git@github.com:kuzzleio/documentation.git

From your local copy of this repository, install all the repos.

kuzdoc install --repo=__ALL__

This wil clone all the repos inside the framework meta-repo.

Note. If you want to put local repositories inside your preview, you can install them before installing all the repos. kuzdoc install will not overwrite repositories that are already installed.

Once all your repos are installed, just launch

kuzdoc local-deploy

The whole docs will be built (this may take a long time) and deployed to /tmp/kuzzle-docs/. You then may run

http-server /tmp/kuzzle-docs/

I want to add a new repo

Repos that are built in the docs are listed in .repos/repositories.json. You can either edit it manually or use the kuzdoc wizard

kuzdoc add-repo

... and just answer the questions.

Organize content

VuePress generates the documentation based on how the files are organized in the filesystem. For example, the URL of each page is direclty infered by its filesystem path relative to src/.

The frontmatter

The left sidebar generation is based on the filesystem location of the files and their frontmatter contents.

A page is defined by a directory (e.g. src/core/1/api/controllers/admin/dump/) containing an index.md file. This file must have a frontmatter with the following form:

---
type: [root|branch|page]
code: [true|false]
title: <Name used in the section list>
order: <Integer> (optional)
description: <(optional) Text appearing under the section name in the section list>
nosidebar: <Boolean> (optional)
---

:warning: No other fields are allowed in the frontmatter

type (required)

Defines how this page behaves in the generation of the sidebar. It is also used by other components (like Algolia indexation). Can be the following values:

• root - The page is the root of the generation of an entire sidebar (e.g. src/code/1/api/);
• branch - The page is a branch of the sidebar and generally has no content but has children (e.g. src/code/1/api/api-reference, src/code/1/api/controllers/admin/);
• page - The page is a "leaf" in the sidebar tree: it has no children and has content. It is indexed to Algolia.

code (required)

A Boolean field defining whether the name of the page must be displayed in monospace typeface in the menu because it indicates the name of a function, a controller or a piece of code in general (e.g. src/code/1/api/controllers/admin/).

title (required)

A String field holding the text to display in the sidebar.

description (optional)

A String field holding a detailed description of the page. Currently used nowhere (I guess).

order (optional)

An Integer field indicating how to sort this page in the sidebar. If absent, the page is sorted alphabetically based on the title field.

nosidebar (optional, default: true)

A Boolean field indicating whether the left sidebar should be displayed for the page or not.

Frontmatter Linter

The build toolchain runs a linter on the frontmatters. If some frontmatters are invalid, the linter makes the build fail and shows the errors to standard output and dumps them to frontmatter-errors.js. Some errors can be automatically fixed: at the end of its report, the linter shows the command to execute to launch the auto-fixer:

$(npm bin)/frontmatter-fix -e frontmatter-errors.js

You can learn more about the linter by looking at its official repository.

The sections

Many other dynamic menus are generated from the src/.vuepress/sections.json file, which consists in a hashmap of sections of this form

{
  "/sdk/go/3/": {
    "kuzzleMajor": 2,
    "section": "sdk",
    "subsection": "go",
    "name": "Golang",
    "version": 3,
    "icon": "/logos/go.svg",
    "released": true
  }
}

The shape of each section is defined in a specific JSON Schema file.

Path

The path to the section in the docs is the key of the element, which prevents from defining the same section twice.

name (required)

The name of the section, mainly use to build the widgets (like the SDK selector, for example).

kuzzleMajor (required)

Defines the major version of Kuzzle this section belongs to (relates to the major version selector).

section (required)

The ID of the section, used when building lists of sections. If the current section is the child of a parent section, this field indicates the name of the parent section. I am very sorry for this horrible naming, I promise I will rename this to parent and make it optional soon.

subsection (optional)

If the section is the child of another section, this field contains the name of the current section. OMG I'm so sorry I'll fix it I promise.

released (required)

Defines if the section is released or not (the section appears in the menus and indexes if true).

version (optional)

If the documented product in the current section has a version, here it goes (like the v7 of the JS SDK v7).

icon (optional)

If the documented product has an icon, this field contains the path.

closedSource (optional)

A boolean indicating whether the documented product is part of Kuzzle Enterprise or not.

deprecated (optional)

Defines if the section shows a header banner saying it is deprecated.

deprecatedBannerComponent (optional)

Contains the name of the name of the banner component indicating the section is deprecated.

I want to add a new section

You can manually edit sections.json or use the kuzdoc wizard

kuzdoc add-section

... and answer the questions.

Writing content

The Kuzzle Docs framework ships with a toolkit allowing to enrich your Markdown content.

Alert and Info boxes

You can create alert/info boxes in your markdown with the following syntax:

::: info
lorem ipsum
:::

Supported containers are : info, success, warning

Tabbed boxes

It is possible to add tabs directly in the markdown with this syntax:

:::: tabs
::: tab Java

<<< ./snippets/check-token.java

:::
::: tab Kotlin

<<< ./snippets/check-token.kt

:::
::::

Library used: https://superbiger.github.io/vuepress-plugin-tabs/#documents

IconTable

You can create a list with icons inside a Markdown file with the IconTable CSS c