diff --git a/docs/_includes/nav.md b/docs/_includes/nav.md index fe587900..728e5444 100644 --- a/docs/_includes/nav.md +++ b/docs/_includes/nav.md @@ -14,15 +14,17 @@ - [Creating Config Files]({{ site.baseurl }}{% link configuration/creating-config.md %}) - [SysOp Setup]({{ site.baseurl }}{% link configuration/sysop-setup.md %}) - [Editing hjson]({{ site.baseurl }}{% link configuration/editing-hjson.md %}) - - [config.hjson]({{ site.baseurl }}{% link configuration/config-hjson.md %}) - - [menu.hjson]({{ site.baseurl }}{% link configuration/menu-hjson.md %}) - - [prompt.hjson]({{ site.baseurl }}{% link configuration/prompt-hjson.md %}) + - [System Configuration]({{ site.baseurl }}{% link configuration/config-hjson.md %}) + - [HJSON General]({{ site.baseurl }}{% link configuration/hjson.md %}) + - [Menus]({{ site.baseurl }}{% link configuration/menu-hjson.md %}) + - [Prompts]({{ site.baseurl }}{% link configuration/prompt-hjson.md %}) - [Directory Structure]({{ site.baseurl }}{% link configuration/directory-structure.md %}) - [Archivers]({{ site.baseurl }}{% link configuration/archivers.md %}) - [File Transfer Protocols]({{ site.baseurl }}{% link configuration/file-transfer-protocols.md %}) - [Email]({{ site.baseurl }}{% link configuration/email.md %}) - [Colour Codes]({{ site.baseurl }}{% link configuration/colour-codes.md %}) - [Access Condition System (ACS)]({{ site.baseurl }}{% link configuration/acs.md %}) + - [Event Scheduler]({{ site.baseurl }}{% link configuration/event-scheduler.md %}) - Scheduled jobs - File Base diff --git a/docs/configuration/config-hjson.md b/docs/configuration/config-hjson.md index 37d07beb..4ebfd030 100644 --- a/docs/configuration/config-hjson.md +++ b/docs/configuration/config-hjson.md @@ -1,10 +1,12 @@ --- layout: page -title: config.hjson +title: System Configuration --- ## System Configuration The main system configuration file, `config.hjson` both overrides defaults and provides additional configuration such as message areas. The default path is `/enigma-bbs-install-path/config/config.hjson` though you can override the `config.hjson` location with the `--config` parameter when invoking `main.js`. Values found in `core/config.js` may be overridden by simply providing the object members you wish replace. +See also [HJSON General Information](hjson.md) for more information on the HJSON format. + ### Creating a Configuration Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your enigma-bbs root directory: ``` diff --git a/docs/configuration/creating-config.md b/docs/configuration/creating-config.md index c8495f1c..5d845d5e 100644 --- a/docs/configuration/creating-config.md +++ b/docs/configuration/creating-config.md @@ -2,26 +2,13 @@ layout: page title: Creating Initial Config Files --- -Configuration files in ENiGMA½ are simple UTF-8 encoded [HJSON](http://hjson.org/) files. HJSON is just -like JSON but simplified and much more resilient to human error. +Configuration files in ENiGMA½ are simple UTF-8 encoded [HJSON](http://hjson.org/) files. HJSON is just like JSON but simplified and much more resilient to human error. -## config.hjson -Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your -enigma-bbs root directory: -``` +## Initial Configuration +Your initial configuration skeleton can be created using the `oputil.js` command line utility. From your enigma-bbs root directory: +```bash ./oputil.js config new ``` -You will be asked a series of questions to create an initial configuration. +You will be asked a series of questions to create an initial configuration, which will be saved to `/enigma-bbs-install-path/config/config.hjson`. This will also produce `config/-menu.hjson` and `config/-prompt.hjson` files (where `` is replaced by the name you provided in the steps above). See [Menu HJSON](menu-hjson.md) and [Prompt HJSON](prompt-hjson.md) for more information. -## menu.hjson and prompt.hjson - -Create your own copy of `/config/menu.hjson` and `/config/prompt.hjson`, and specify it in the -`general` section of `config.hjson`: - -````hjson -general: { - menuFile: my-menu.hjson - promptFile: my-prompt.hjson -} -```` \ No newline at end of file diff --git a/docs/configuration/hjson.md b/docs/configuration/hjson.md new file mode 100644 index 00000000..a4eda583 --- /dev/null +++ b/docs/configuration/hjson.md @@ -0,0 +1,39 @@ +--- +layout: page +title: HJSON General Information +--- +## JSON for Humans! +HJSON is the configuration file format used by ENiGMA½ for [System Configuration](config-hjson.md), [Menus](menu-hjson.md), [Prompts](prompt-hjson.md), etc. [HJSON](https://hjson.org/) is is [JSON](https://json.org/) for humans! + +For those completely unfamiliar, JSON stands for JavaScript Object Notation. But don't let that scare you! JSON is simply a text file format with a bit of structure ― kind of like a fancier INI file. HJSON on the other hand as mentioned previously, is JSON for humans. That is, it has the following features and more: + +* More resilliant to syntax errors such as missing a comma +* Strings generally do not need to be quoted. Multi-line strings are also supported! +* Comments are supported (JSON doesn't allow this!): `#`, `//` and `/* ... */` style comments are allowed. +* Keys never need to be quoted +* ...much more! See [the official HJSON website](https://hjson.org/). + +## Terminology +Through the documentation, some terms regarding HJSON and configuration files will be used: + +* `config.hjson`: Refers to `/path/to/enigma-bbs/config/config.hjson`. See [System Configuration](config-hjson.md). +* `menu.hjson`: Refers to `/path/to/enigma-bbs/config/-menu.hjson`. See [Menus](menu-hjson.md). +* `prompt.hjson`: Refers to `/path/to/enigma-bbs/config/-prompt.hjson`. See [Prompts](prompt-hjson.md). +* Configuration *key*: Elements in HJSON are name-value pairs where the name is the *key*. For example, provided `foo: bar`, `foo` is the key. +* Configuration *section* or *block* (also commonly called an "Object" in code): This is referring to a section in a HJSON file that starts with a *key*. For example: +```hjson +someSection: { + foo: bar +} +``` +Note that `someSection` is the configuration *section* (or *block*) and `foo: bar` is within it. + +## Editing HJSON +HJSON is a text file format, and ENiGMA½ configuration files **should always be saved as UTF-8**. + +It is **highly** recommended to use a text editor that has HJSON support. A few (but not all!) examples include: +* Sublime Text 3 via the `sublime-hjson` package. +* Visual Studio code via the `vscode-hjson` plugin. +* Notepad++ via the `npp-hjson` plugin. + +See https://hjson.org/users.html for more information. diff --git a/docs/configuration/menu-hjson.md b/docs/configuration/menu-hjson.md index 1956252c..d5e9b66d 100644 --- a/docs/configuration/menu-hjson.md +++ b/docs/configuration/menu-hjson.md @@ -1,9 +1,9 @@ --- layout: page -title: menu.hjson +title: Menus --- -## Menu HJSON -The core of a ENiGMA½ based BBS is `menu.hjson`. Note that when `menu.hjson` is referenced, we're actually talking about `config/yourboardname-menu.hjson` or similar. This file determines the menus (or screens) a user can see, the order they come in and how they interact with each other, ACS configuration, etc. Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format. +## Menus +The core of a ENiGMA½ based BBS is `menu.hjson`. Note that when `menu.hjson` is referenced, we're actually talking about `config/yourboardname-menu.hjson` or similar. This file determines the menus (or screens) a user can see, the order they come in and how they interact with each other, ACS configuration, etc. Like all configuration within ENiGMA½, menu configuration is done in [HJSON](https://hjson.org/) format. See [HJSON General Information](hjson.md) for more information. Entries in `menu.hjson` are often referred to as *blocks* or *sections*. Each entry defines a menu. A menu in this sense is something the user can see or visit. Examples include but are not limited to: diff --git a/docs/configuration/prompt-hjson.md b/docs/configuration/prompt-hjson.md index 7b7a3ab5..993e5b8e 100644 --- a/docs/configuration/prompt-hjson.md +++ b/docs/configuration/prompt-hjson.md @@ -3,4 +3,6 @@ layout: page title: prompt.hjson --- :zap: This page is to describe general information the `prompt.hjson` file. It -needs fleshing out, please submit a PR if you'd like to help! \ No newline at end of file +needs fleshing out, please submit a PR if you'd like to help! + +See [HJSON General Information](hjson.md) for more information.