Quick Style Guide

This page serves as a quick style guide, to establish rules and best practices for IKANOWS documentation.

Using the Table of Contents

You can dynamically generate a table of contents (TOC) using the TOC macros.  The TOC on this page (above) uses the macros.  It has been configured with a minimum level of H2.

Headings

Headings are used to organize content on the page.  It is possible to use up to 6 level headings per page, but this is rarely practical.   A best practice for IKANOWS documentation is to use 3 heading levels.

The headings are used by the TOC plugin to dynamically generate the table of contents for the page.

Heading 3

Example level 3 heading.

Horizontal Lines

Horizontal Lines are used to improve scanning/localization by providing a visual separator between each H2 section.  Refer to the formatting of this page by way of example. A line break should appear both before and after each horizontal line, for enhanced localization.

Using Code Snippets

Code snippets are used by way of example wherever appropriate.  The Code Block macros is used for each code snippet.

Example:

"extraUrls": [ // This array allows for manually specified URLs to be harvested once        {
            "url": string, // The URL 
            "title": string, // The title that the document will be given (ie the equivalent to the RSS title)
            "description": string, // (Optional) The description that the document will be given (ie the equivalent to the RSS description)
            "publishedData": string, // (Optional) The date that will be assigned to the document (default: now) - this can be overridden from "structuredAnalysis"
            "fullText": string //
 (Optional) If present and "useTextExtractor" is "none", then uses the 
specified string instead of the URL contents (mainly for debugging)

Special Conventions

The following conventions are applicable.

Footnotes

The panel macros is used to indicate any footnotes at the bottom of the page. For example, links to legacy documentation.