Documentation
    {{docApp.userSession.userId}}
    {{docApp.userSession.userName}}
    {{docApp.userSession.email}}
    Issuer : {{docApp.userSession.issuerInstance}}
    Expires : {{new Date(docApp.userSession.validUntil).toLocaleDateString()}}

{{docApp.title}}

{{docApp.description}}

INDEX

Documentation Library

Search for information on Hornbill Documentation.

{{docApp.searchError}}

{{docApp.searchResultFilteredItems.length}} results for "{{docApp.currentResultsSearchText}}" in {{docApp.searchFilterBySpecificBookTitle}}

Have questions about this site?

What is this site?

  • This website is Hornbill's new product documentation website and is currently under development.
  • It is intended that all existing and future public-facing documentation we produce will be available to search, browse and share.
  • Hornbill's current documentation is available at Hornbill Wiki but over time this content will be migrated to this documentation site.
  • Please feel free to have a look around at any time.

Why has Hornbill created this site?

  • Hornbill's products have moved on considerably since we introduced it almost 10 years ago. At the time, the MediaWiki tool was sufficient, but we have outgrown it.
  • Our customers are more enterprise focused and more self-sufficient than ever before, so for 2023 and beyond we have established a new documentation platform and team to drive our documentation initiative forwards.
  • We are aiming to deprecate the use of Hornbill Wiki for most Hornbill related documentation.
  • We want to enable our growing partner network with product resources and information, documentation beyond our Wiki approach is required.
  • We could definitely do with some help, and may even pay for some! If you have domain knowledge and would like to help, please check out our Hornbill Docs Contributor Guide and contact the Hornbill docs team at docs@hornbill.com.

What will this site be good for?

  • Community contribution will be facilitated, encouraged, and most welcome.
  • High quality documentation, will be kept up to date as rapidly as our products evolve.
  • Real-time content search and discovery.
  • Articles organized into books, books into libraries, creating a more natural and logical structure to our documentation.
  • Legacy API documentation and various other documentation sources will all be consolidated into a single unified documentation system.
  • Documentation available in browser as well as printable/viewable as PDF on demand.
  • Personalized documentation experience, allowing dark/light mode, article subscriptions, social media sharing and other useful features.
  • Almost all publicly available documentation on docs.hornbill.com will be open-source and available to fork on GitHub, allowing customers to derive their own custom documentation around Hornbill products should they wish to.

What is the timeline for this site?

  • We have taken the decision to publish and make available early, there is very little content at this time.
  • As and when we have completed/usable documentation, it will be published here.
  • We have a host of additional features we wish to add over time, so please watch this space.
  • We expect most of our existing documentation should be reviewed/migrated to docs.hornbill.com over the coming months.
  • The documentation project will be ongoing, will continue to expand, evolve and improve day-by-day.

{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}

{{docApp.libraryHomeViewProduct.description}}

  1. {{book.title}}

{{group.title || group.id}}

{{group.description}}

  1. {{book.title}}

{{group.title}}

{{book.title}}
More...

HDocBook Overview

A HDocBook (or book for short) is the name we give to a collection of individual, but related Articles. As well as including a collection of written articles that make up the content of the book, a HDocBook provides the wrapper for containing and referencing supporting assets like images, downloadable files, icons and other static resources. Like a physical book, this Book Package also includes the definition of a book’s primary navigation index and table of contents, as well as other metadata to describe the books position in the Hornbill Docs library taxonomy. Other metadata that helps the Hornbill Docs search function includes information about the book such as subject, summary, keywords, tags and other such metadata that helps keeps books organization, categorized and easily searchable. You can think of a Book analogous to a physical book.

An Article is what we call an individual page within a Book, an Article can be a single page of information or can be many screens full of information. A HDocBook will have an automated H2/H3 generated table of contents, which provides navigation links to locations within the current page. The key attribute that defines a document as an Article is, it is represented physically, by a single file. Articles are generally written using Markdown HDocBook Markdown, but where required, in special cases, they can be written using raw HTML.

Caution

When writing article content in HTML, you should ensure the HTML code you generate is compatible with the semantics, as well as the CSS we are using for layout/content positioning.

In source code form, a book is simply a folder with certain mandatory files and folders, organized into a well defined structure. A file called hdocbook.json must be included in the root folder, this file which essentially includes all of the metadata required to create the book, as well as metadata that controls publishing, indexing and taxonomy attribution.

Developing content for the Hornbill Docs system is supported with development tools created by the the Hornbill Docs team. These tools are available to install as part of your local Node.js and Node Package Manager (npm) deployments.

The Anatomy of a Book

All books have a number of immutable characteristics, including a Globally Unique Identifier (called a slug), a Title, a Summary Description, a Table of Contents, as well as metadata that defines/controls publishing and presentation options, as well as information that helps organize Books into a structured taxonomy.

Book Unique Identifier (slug)

Each book is allocated a unique identifier, this is in the form of a lower-case-multi-word-hyphen-separated text string. When consuming the content pages of the book, this slug is always included in the URL when accessing the book content, so forms part of the final SEO optimization in relation to the search engine, crawling and final content location URL.

Book Content

Document content is written in Markdown. Markdown is a plain text-based content writing system that uses very simple markup to control aspects of page layout and presentation, while at the same time providing a complete separation of concerns between content and presentation.

Markdown is a simple plain text scheme for marking up a document, that document can then be rendered using web pages, PDFs or other formats on many different device and screen types. Using Markdown ensures that content writers can focus on content and not have to worry about presentation and design issues such as fonts, colors, page alignment and so on.

If required, there are more advanced options to use HTML and inline CSS instead of Markdown to create custom layouts and presentations, but this is encouraged only for very special situations where Markdown is simply not an option. The markdown syntax is based on the CommonMark standard, but the HDocBook specification also includes additional custom elements that are specialized for this type of documentation content rendering.

Table of Contents

A Book includes the definition of a table of content, which is presented on the left-hand navigation panel of links to pages, the table of contents can be a simple vertical list of links, or, can be a hierarchical tree of up to three levels deep leading to links. An entry in the table of contents tree can either be an expandible/collapsible “group of items” - OR - an item, which is link to an article and/or page anchor.

Anchor Shortcut Table

For larger articles, where the content spans multiple screen pages, it is possible to enable an Article Anchor Link Shortcut Table. This table appears at the top-right of the content page, and is automatically generated to include anchor links to all H2 and H3 content headings that have been written into the document.

Access Controls

A Book includes metadata and options that allow you to control who should be able to see the document. These access controls make it possible to give different people different levels of visibility/access to documentation, all through the same documentation website.

Internationalization

Books may contain pages for multiple languages if required, this is achieved by writing the main page in the default language (English), and then, you can write one or more language variants of each page.

  • Version {{docApp.book.version}}
  • Node {{docApp.node}} / {{docApp.build}}
In This Document