- Usage
- File organization
- File headers
- Sorting the documentation
- Configure versions
- Troubleshooting
- See also
install dependencies
npm install
index documentation content to algolia
node index.js --algolia-private-key <key>
index documentation content to algolia matching version configured in versions.config.json
node index.js --build-path /v/edge --algolia-private-key <key>
build the documentation in production mode matching version configured in versions.config.json
node index.js --build-host https://docs.kuzzle.io --build-path /v/edge --build-compress
bind a webserver on 8080 with livereload and watch enabled
node index.js --dev --watch
npm run dev
bind a webserver on 80 with livereload, open a browser, turn on debug messages and check dead links
sudo DEBUG=* node index.js --dev --watch --open-browser --port 80 --ckeck-links
Here is an overview of the files structure:
src/
: documentation entry pointsrc/<section>/
(for instance:src/guide/
, entry point of the Guide documentation section)src/<section>/<subsection>/
(for instance:src/guide/essentials/
)src/<section>/<subsection>/<article>.md
(for instance:src/guide/essentials/installing-kuzzle.md
)
Though there is no real limit to the directories depth, to keep the documentation homogeneous and readable, no additional subdirectories should be added.
Sections are listed as subdirectories in src/
.
For instance: src/guide/
.
Each section directory must contain an index.md
file, with the following headers:
---
layout: category-childrens.html
title: <Name used in the section list>
order: <(optional, integer)>
description: <(optional) Text appearing under the section name in the section list>
icon: <font-awesome icon name>
---
For more information about headers, see the file headers documentation.
Subsections are directories listed under a section directory.
For instance: src/guide/essentials/
A subsection has one of the 3 following behaviors:
- Articles container (e.g.
/sdk-reference/essentials/
). This is the default behavior when markdown files other thanindex.md
are present in the subsection directory. When selected:- lists articles stored in the subsection
- does NOT appear itself in the articles list (the
index.md
content is ignored) - shows the first article documentation found in the list
- Standalone article (e.g.
/guide/getting-started/
). This is the default behavior whenindex.md
is the only file in the subsection directory. When selected:- does not deploy any articles list
- shows the
index.md
content directly
- Articles container + standalone article (e.g.
/guide/essentials/
). This behavior can only be activated through the show-subheader header. When selected:- lists articles stored in the subsection
- lists
index.md
as the first article available, using the optional subheader-title header value (or the title one if not set) - shows the
index.md
content directly
Each subsection directory must contain an index.md
file, with the following headers:
---
layout: <full.html or category-members.html>
algolia: [true|false]
title: <Name used in the subsection list>
description: <(optional) Text appearing under the subsection name in the subsection list>
order: <(optional, integer)>
show-subheader: <(optional, boolean, default: false)>
subheader-title: <(optional, default: title header value)>
---
For more information about headers, see the file headers documentation.
Articles are markdown files stored under a subsection directory.
For instance: src/guide/essentials/installing-kuzzle.md
Each article file must contain a header with the following properties:
---
layout: <full.html or side-code.html>
algolia: [true|false]
title: <Article name in the subsection list>
order: <(optional, integer)>
---
For more information about headers, see the file headers documentation.
Here is a rundown of the possible header values that can be configured in markdown files:
Type: bolean
Default: true
Enable disqus comment plugin on page.
The layout
header sets the way the selected page is displayed:
category-childrens.html
: fit for sections, this layout displays the section title, its description, and a list of available subsectionscategory-members.html
: fit for subsections without content to display in theirindex.md
file, this layout displays a list of available articlesfull.html
: fit for articles without code example, this layout displays the content of the article, with a table of content navigation menuside-code.html
: fit for articles embedding code examples, this layout displays the content of the article on the left, and code examples on the right part of the page
Type: integer
Default: <undefined>
Defines the section, subsection or article position relative to others.
For more information, see how the documentation is sorted
Type: boolean
Default: false
To be used only on subsection
index.md
files.
By default, we configured this documentation to hide the content of index.md
files in subsections (see documentation subsections).
This header makes the content of index.md
appear like any other article, using the subheader-title title if set (or the title header otherwise).
Type: string
Default: <undefined>
If show-subheader is set to true
, then this value is used as the article name in the navigation bar.
Type: boolean
Default: <undefined>
If the page has no siblings (thus, is the index.md
of a section), it can have a Table of Contents displayed in the second level of the left menu. Only the h2
headers are shown in the TOC.
Inside each category (section, subsection, article), all files are automatically sorted.
The final order of sections, subsections or articles depends on two values: the order header and the title header, the former having precedence over the latter:
- if no
order
header is specified across all files of the same category (section, subsection, or article), sorting is done solely using thetitle
header - if there is a mix of files with the
order
header while others don't have one:- files with the
order
header are sorted relative to each other and put at the start of the list - then, files without this header are sorted using their
title
header value, and put afterward
- files with the
Example:
The SDK reference contain subsections, each one with a index.md
file:
/sdk-reference/essentials/index.md
has an order set to0
/sdk-reference/kuzzle/index.md
has an order set to100
- all other subsections are without an
order
header: they are listed afteressentials
andkuzzle
subsections, but sorted using their title header value
Version configuration are set in versions.config.json
file
JSON Key | Value | Usage |
---|---|---|
version_label |
string |
Label displayed in version selector |
version_path |
string |
Base path used to generate links (should start and end with a slash / ) |
algolia_index |
string |
Used to distinguish algolia search index |
version_gh_repo |
string |
Linked git repository (used by file edition) |
version_gh_branch |
string |
Linked git branch (used by file edition and travis deploiement) |
Once version have been configured on versions.config.file
, enable auto deployment
adding your branch configured in version_gh_repo
to .branches.only
entry in .travis.yml
file
[
{
"version_label": "1.0.0-rc9 (latest)",
"version_path": "/",
"algolia_index": "kuzzle-documentation",
"version_gh_repo": "kuzzleio/documentation",
"version_gh_branch": "master"
},
{
"version_label": "1.0.0-rc10 (next)",
"version_path": "/v/edge/",
"algolia_index": "kuzzle-documentation",
"version_gh_repo": "kuzzleio/documentation",
"version_gh_branch": "rc.x"
}
]
You have to increase the max_user_watches
variable, run the following command :
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p