OrchidWiki

A Gitbook-like wiki for your Orchid site.


About

Publish searchable and easily-navigable wikis, inspired by the legacy GitBook CLI, and generate PDFs for offline viewing.

Installation

dependencies {
    orchidRuntime("io.github.javaeden.orchid:OrchidWiki:0.21.2")
}
<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>OrchidWiki</artifactId>
    <version>0.21.2</version>
    <type>pom</type>
</dependency>
libraryDependencies += "io.github.javaeden.orchid" % "OrchidWiki" % "0.21.2"
@file:DependsOn("io.github.javaeden.orchid:OrchidWiki:0.21.2")

Demo

Usage

Basic Usage

An Orchid Wiki is a collection of pages structured in a freeform hierarchy. Pages in a wiki are all related and ordered, with one page linking directly to the next so a user can read the entire contents of the wiki from front-end simply by navigating the page links. Orchid Wikis also create Menu items which display the full wiki tree in an easily navigable fashion.

Wikis in Orchid are inspired by GitBook and are set up in a similar manner. To start, add a file named summary (in your language of choice) to wiki/. This file becomes the landing page for the wiki and can contain any kind of content, which gets displayed exactly as written. But it also gets converted to HTML and all links in this file become a page in the wiki.

For example:

### Wiki Heading

[Getting Started](getting-started.md)
[Basic Setup](setup/basic.md)
[Advanced Setup](setup/advanced.md)

corresponds to the following directory structure:

. / (resources root)
├── homepage.md
├── config.yml
└── /wiki
    ├── summary.md
    ├── getting-started.md
    └── /setup
        ├── basic.md
        └── advanced.md

which produces the following output:

. /wiki
├── /summary
|   └── index.html
├── /getting-started
|   └── index.html
└── /setup
    ├── /basic
    |   └── index.html
    └── /advanced
        └── index.html

The content of those wiki pages can be anything, and can be written in any language as long as there is a Compiler for it (just like the summary, and any other page). Orchid also creates a new menu item type which links to every page in the wiki and is displayed recursively in the same hierarchy as the pages themselves.

Wiki Sections

You can set up multiple wiki sections which each have their own summary file, pages, and menu items. The following snippet should go in your site's config.yml:

wiki:
  sections:
    - 'userManual'  # (1)
    - 'developerGuide'  # (2)
  1. Creates a wiki based on {baseDir}/userManual/summary.md, and lives at /wiki/userManual
  2. Creates a wiki based on {baseDir}/developerGuide/summary.md, and lives at /wiki/developerGuide

You can configure all your sections at once by putting configuration values under the defaultConfig property.

wiki:
  sections:
    - 'userManual'
    - 'developerGuide'
  defaultConfig: // applied to both userManual and developerGuide sections 
    createPdf: true

If you have more than one section in your site, a "section index" page will also be created, linking to each individual section. This index file will live at /wiki.

Offline Documentation

As of 0.13.0, the wiki plugin includes support for offline documentation. PDFs are an opt-in feature; to enable PDF generation, simply add createPdf: true to the section configuration for have it generate a PDF with all the content for that section of your wiki. Each section will now generate book.pdf in the section root.

wiki: 
  sections:
    - key: userManual
      createPdf: true
    - key: developerGuide
      createPdf: true

The PDF starts with the section summary.md as a Table of Contents, and each page in the wiki starts after a page break in the PDF, and the TOC links to each page. You may override templates/wiki/book.peb to customize your PDFs as needed. PDFs are generated from HTML using the OpenHTMLToPDF library.

Wiki Adapters

Orchid is able to connect to external Wiki services, which provide content to embed in an Orchid site. This allows you to effectively use these services as a headless CMS and let Orchid publish them as a full website alongside your other documentation and content, utilizing the other Orchid features you love like full-text search and PDF generation for offline viewing.

The following plugins provide adapters to external Wikis:

Adapters can be set individually for each Section in your wiki by declaring the intended adapter and its options in you config.yml. See the plugin pages linked above for more info on configuring each wiki adapter.

wiki: 
  sections:
    userManual:
      adapter: 
        type: "github"
        repo: "copper-leaf/wiki-with-sidebar"
    developerGuide:
      adapter: 
        type: "gitlab"
        repo: "cjbrooks12/wiki-without-sidebar"