Custom content

Information related to creating custom content packs for the OBR Compendium Browser.

In addition to the various preconfigured packs available for the Compendium Browser, it's also possible for users to create their own packs of custom content. This is useful not only for homebrewed content, but it also allows you to include documents for published content that is not otherwise available, perhaps due to licensing restrictions.

Creating Custom Content Packs

All content packs for the OBR Compendium Browser are JSON documents that follow a particular structure or "schema". You can find detailed information about the valid schema for compendium content in the Document Schema section.

The most basic valid format for a compendium pack is as follows.

{
    "name": "My Compendium Pack",
    "id": "my-compendium-pack",
    "documents": []
}

Every pack needs to have a human-friendly name for when users need to interact with the pack in some way via the OBR Compendium Browser interface. Additionally, you must provide a unique ID for your pack. Since this is only used behind the scenes, it's a good idea to use a tool like this to generate a long, unique string of characters. Finally, a pack must contain an array of documents. Each of these documents must conform to one of the defined document schema detailed in the next section.

Optionally, compendium packs may include a version number matching the SemVer specification, like so.

{
    "name": "My Compendium Pack",
    "id": "my-compendium-pack",
    "version": "1.0.0",
    "documents": []
}

Version numbers are mostly useful for published packs you intend to distribute to other users, as these numbers are used to provide information when a user uploads a file for a pack that already exists.

The order of the keys in your JSON document is irrelevant; however, it is essential that they are otherwise written exactly as presented above. Casing is important, and JSON keys must be wrapped in quotation marks.

Document IDs

By default, a document will be assigned a random, unique ID when a pack is installed. If a document already has an ID, this step is skipped, providing a permanent handle for referencing the document.

If you provide IDs for some or all of the documents in your pack, the IDs must be unique within that pack. Duplicate IDs will cause the pack to fail validation, preventing installation.

Document Linking

The Compendium Browser provides a special syntax for generating a document reference within fields that accept HTML. In order to link to another document, you need both the id of its parent pack and the id of the document you want to reference within that pack.

The syntax is as follows:

@documentLink{ packID="somePackID", documentID="someDocumentID" }(My Document)

If the above string were included in an document description field, for example, it would be replaced with the words, "My Document". These words would be specially formatted, and would act as a link to a document with the ID, "someDocumentID" that lives inside a pack with the ID, "somePackID".

Note that you can use either single or double quotes to wrap the packID and documentID.

Example Usage

"description": "Take a look at @documentLink{ packID='somePackID', documentID='someDocumentID' }(My Document)!"

Users would see:

Take a look at My Document!