This GitHub project is an initiative of WoodWing Software. It provides a simple framework to write and publish technical documentation for the Enterprise system. Through this channel WoodWing engineers can update partners and integrators with technical information helping them to integrate their own solutions with Enterprise.
This GitHub project is using Jekyll and is ran by the GitHub Pages server. For maintance and testing, you can run it locally as decribed here before you push your changes to Git.
This project provides a simple documentation structure. It uses the MarkDown standard to take away the clutter of the HTML notation. It offers a generator for the Table Of Contents which hyperlinks that are automatically updated. This makes it easy to add, update, delete or move guides, sections and chapters. How this is organised is explained in the chapter below.
At the root level of this project there are folders. Each folder reprensents a guide. A guide can be seen as a book. In the folder of a guide there must be an index.md file. This is the landing page of the guide. The front matter of this page must have the follow attributes:
layout: guide
title: <the title of the guide>The layout property is used to select the HTML page. In this
case the _layouts/guide.html page is applied.
A guide may have many chapters. Those may be bundled in sections. To add a section to a guide, simply create a subfolder in the guide's folder and add an index.md file with the folliwng front matter:
layout: section
title: <title of the section>The layout property is used to select the HTML page. In this
case the _layouts/section.html page is applied.
Chapters can be added to a guide or to the section of a guide. For each chapter a markdown file/page should be added to the folder of the guide or the section. The front matter of this page must have the follow attributes:
layout: chapter
title: <title of the chapter>
sortid: <number representing the order within the folder>The sortid gives control over the position the chapter is shown
in the Table Of Contents. Chapters are sorted per folder whereby the
the chapter with lowest number is shown first.
The layout property is used to select the HTML page. In this
case the _layouts/chapter.html page is applied.
The TOC can be generated. This is needed after making structural changes to the guide, such as adding chapters to moving files. To generate the TOC please enter the following commands at the shell prompt:
$ cd <this_project_folder>/_build
$ php generate.php
For each guide a TOC is generated at _data/<guide>/toc.yaml.
This YAML file is read by _includes/toc.htm to compose a HTML
variant and injected by the layout pages by a simple include
instruction {% include /toc.html %}.
There is a Google-like search feature provided that is based on Lunr. It is entirely written in JavaScript and uses a search index file. To generate the search index file please enter the following commands at the shell prompt:
$ cd <this_project_folder>/_build
$ php generate.php
For each guide, the generator reads all text content from the Markdown files/pages and adds one
record for each file/page in the index file. For each guide a search index file is generated at
assets/<guide>/search_data.json. The index file is downloaded by JavaScript as executed
by the search page.
Whenever you change text content of a guide, the generator should be executed to reflect
those changes in the search results.
The following 3rd party resources are used:
- Background image used in page banners: https://pngtree.com/freebackground/electronic-technology-background-vector-banner_24720.html
- Icons used in page navigation buttons: https://icomoon.io/app/#/select
- Animated books used in landing page: https://tympanus.net/Development/AnimatedBooks/
- Lunr used for indexed text search: https://lunrjs.com/
- jQuery: https://jquery.com/