Cyclops Infobook HTML

Output Cyclops infobooks as HTML.

This tool is the basis for the following mod-specific plugins:

• infobook-html-integrateddynamics.
• infobook-html-evilcraft.

Usage

This tool allows Cyclops infobooks to be exported as an HTML website in four phases:

1. Metadata generation: A preparation step for generating all required metadata that is needed for serializing the infobook to HTML.
2. Icon generation: Exporting item and block icons to PNG files.
3. HTML generation: Serialization to HTML based on the infook XML and metadata.
4. Icon compression: Optionally compress icons within the output directory.

1. Metadata Generation

This step will start a Forge server with your mods so that all relevant metadata can be exported to JSON files.

Before you can execute this phase, you need a modpack.json file with contents that look as follows:

{
  "minecraft": "1.12.2",
  "forge": "14.23.5.2838",
  "mods": [
    {
      "type": "curseforge",
      "project": "cyclops-core",
      "artifact": "CyclopsCore-1.12.2",
      "version": "1.4.0"
    },
    {
      "type": "maven",
      "artifact": "org.cyclops.integrateddynamics:IntegratedDynamics:1.12.2-1.0.9-1317",
      "repo": "https://oss.jfrog.org/artifactory/simple/libs-release/"
    },
    {
      "type": "maven",
      "artifact": "org.cyclops.commoncapabilities:CommonCapabilities:1.12.2-2.4.4-309",
      "repo": "https://oss.jfrog.org/artifactory/simple/libs-release/"
    },
    {
      "type": "raw",
      "name": "integratedscripting-1.19.2-1.0.0-61.jar",
      "url": "https://www.dropbox.com/s/mbbikni5ieyttuq/integratedscripting-1.19.2-1.0.0-61.jar?dl=1"
    }
  ]
}

The "forge" entry may be replaced by "neoforge".

To start this phase, simply run generate-mod-metadata modpack.json generate.

Optionally, you can delete the resulting server files afterwards using generate-mod-metadata modpack.json clean.

If you want to re-download the mods without re-installing Forge, you can run generate-mod-metadata modpack.json cleanmods.

2. Icon Generation

This phase can be done manually using the Icon Exporter mod, or automatically.

Manual icon generation

Simply create a modpack with all the mods that were downloaded in the previous step (including the Item Exporter mod), start a world, and run the /iconexporter export 64 command.

Next, copy the resulting contents of icon-exports-x64 to icons in your project directory.

Automatic icon generation

The generate-icons command can be executed, which will cause a Headless Minecraft instance to be downloaded and started, and the Icon Exporter mod to be ran.

When running this on a headless machine, you should have xvfb installed and running. For example:

$ sudo apt-get install -y xvfb
$ xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" generate-icons

3. HTML Generation

Before you start this phase, make sure the following files and directories are present:

• registries/crafting_recipe.json: All crafting recipes. (Generated in Metadata Generation)
• registries/item_translation_keys.json: A mapping from all items to translation keys. (Generated in Metadata Generation)
• registries/fluid_translation_keys.json: A mapping from all items to translation keys. (Generated in Metadata Generation)
• mod_assets/ The mod asset files extracting from the mod jars. (Generated in Metadata Generation)
• config.json: A configuration file with the following contents:

{
  "baseUrl": "/",
  "googleAnalytics": "UA-???????-??",
  "googleAdsense": {
    "client": "ca-pub-?",
    "slot": "?",
    "format": "auto"
  },
  "colors": {
    "h": "#16384c",
    "border": "#3381ad",
    "border_light": "#49b8f7",
    "border_muted": "#9fcae3",
    "main_background": "#e6d6ac",
    "outer_background": "#09171f"
  },
  "icon": "https://media.forgecdn.net/attachments/70/844/logo.png",
  "bookIconItem": "integrateddynamics:on_the_dynamics_of_integration",
  "search": true,
  "modId": "integrateddynamics",
  "modName": "Integrated Dynamics",
  "modUrl": "https://www.curseforge.com/minecraft/mc-mods/integrated-dynamics",
  "bookName": "On the Dynamics of Integration",
  "sectionsFile": "mod_assets/integrateddynamics/info/on_the_dynamics_of_integration.xml",
  "injectSections": {
    "info_book.integrateddynamics.manual": [
      {
        "sectionsFile": "mod_assets/integratedtunnels/info/tunnels_info.xml",
        "modId": "integratedtunnels"
      }
    ],
    "info_book.integrateddynamics.tutorials": [
      {
        "sectionsFile": "mod_assets/integratedtunnels/info/tunnels_tutorials.xml",
        "modId": "integratedtunnels"
      }
    ]
  },
  "keybindings": {
    "key.integrateddynamics.logic_programmer_focus_search": "Alt + F",
    "key.integrateddynamics.logic_programmer_open_rename": "Alt + R"
  },
  "recipeOverrides": {},
  "recipePredefineds": {}
}

Some of these options deserve a note:

• colors: The palette the stylesheet derives all of its colors from, so that the generated pages match the look of the book inside the game.
• icon: The URL of the favicon and the Open Graph image.
• bookIconItem: Optional id of the item of which the exported icon is shown next to the book name in the header of every page, which is usually the book itself. It falls back to icon when it is not set, and icon falls back to it when icon is not set.
• search: Set to false to leave out the search interface. See below.

This phase can be started by executing generate-cyclops-infobook-html config.json /output. Afterwards, the contents of /output can be hosted on any Web server.

4. Search

After the pages have been written, they are indexed for search with Pagefind, which writes the index into output/pagefind/. Every page then offers a search dialog, opened from the header or with Ctrl/Cmd + K.

The index is split per language and into chunks, so a reader only downloads the parts needed to answer their query, and search keeps working on a plain static host. Pages are indexed in the language of their lang attribute, so readers search the book in the language they are reading it in.

Only the page itself is indexed: the navigation, breadcrumbs and page buttons are left out, so results are about content rather than the chrome around it.

Indexing adds roughly 5 KB per page to the output, most of it the excerpt shown with each result. For a book of 1000 pages across all its languages that is about 6 MB. It can be tuned in config.json:

{
  "search": false
}

{
  "search": {
    "glob": "**/*.html",
    "excludeSelectors": [".my-noisy-widget"]
  }
}

• false leaves out both the index and the search interface.
• glob restricts which files are indexed, relative to the output directory.
• excludeSelectors drops parts of the page from the indexed text.

5. Icon Compression

Using the compress-icons command, icons within the output/ directory will be compressed. This is recommended when deploying the output to a web server.

Plugins

Optionally, plugins can be loaded to for example add support for non-default appendix handlers.

This can be done by implementing IInfobookPlugin, and exporting an instance of it via a JavaScript file.

Next, the plugin can be loaded when generating HTML by adding the following to your config.json file:

{
  "plugins": [
    "path/to/instance.js"
  ]
}

Example: Integrated Dynamics plugin

License

This software is written by Ruben Taelman.

This code is released under the MIT license.