Doc contents

Doc-contents is the root folder of the documents and collections. The way in which this folder is organised is strictly depending on the structure you want to have for your documentation, there is no limitation in this matter.

However, some sub-folders are necessary to be present:

_faq: the collection folder where the Q&A files must be placed if a FAQ section is enabled for the site
downloads: the folder where is recommended to place the download files, see also Download component
partials: the folder where is recommended to place reusable content. The structure of this folder is not limited.
_tools: the folder in which the helper pages are placed

These folders **must not be removed** as they are used for specific purposes when building the site.

Doc init

After cloning or downloading Docaroo repository it is needed to setup your documentation root folder (doc-contents). Remove the default one (which contains this documentation) and replace it with the one found in the start-up folder, having the structure shown below.

📁 doc-contents/
├── 📁 _faq
│   └── 📄 readme.md
├── 📁 _tools
│   ├── 📄 cat-info.md
│   ├── 📄 site-pages.md
│   └── 📄 tag-info.md
├── 📁 downloads
│   └── 📄 readme.md
├── 📄 intro.md
└── 📁 partials
    ├── 📁 media
    │   └── 📄 readme.md
    └── 📄 readme.md

Observe that we provide also an example of the entry point to your documentation (intro.md). Feel free to modify it as needed. This document is already configured as the entry point to your documentation (a button link pointing to it is visible in the head section of the home page). You can always modify it in _data/pageBuildConfig.yml, under the home page (\) configuration section. The permalink of the entry point document is the value of startPermalink key, while the text shown on the link button is the value of startBtnText key.

/":
  enabled: true
  startPermalink: "/intro/"
  sections:
    header_section:
      title: "Documentation site framework"
      text: > 
        Build your own documentation site without breaking a sweat! Let your users play boss and organize info however they want — neat, messy, or somewhere in between. And with lightning-fast search tools, finding what they need is quicker than you can say “Where’s that doc again?” Making docs easy, fun, and seriously powerful — all wrapped up in one neat package.
      startBtnText: "Overview"
      

After creating the root folder of your documentation, you can start adding documents and collections of documents. Remember, the key of a good documentation is the way in which you structure it. Another key success point is to identify the reusable content and to not duplicate pieces of content in your documentation. This way you will avoid heavy documentation maintenance and inconsistency of your content.

Content strategy

Collections

Using collections is the best way to group your documentation in thematic sections. Docaroo works with two types of collections, custom collections and default collections.

While there is no limitations when defining custom collections, the default collections configuration must not be changed.

Definition

Inside the documentation root folder (doc-contents), the collections are defined as folders having the name starting with _. Besides of the collections folders, collections are defined in _config.yml configuration file as is shown below.

It is not enough to create a folder having the name starting with _ to use it as collection. It is necessary to do the proper configurations in _config.yml too.

collections:

  # custom collections
  content:
    permalink: "/:collection/:path"
    output: true
  components:
    permalink: "/:collection/:path"
    output: true
  experiments:
    permalink: "/:collection/:path"
    output: true
  taxonomies:
    permalink: "/:collection/:path"
    output: true
  

  # default collections (last position(s)) --- do not modify
  tools:
    permalink: "/:collection/:path"
    output: true
  faq: # no output for faq collection
    permalink: "/:collection/:path"
    output: false


# see https://just-the-docs.com/docs/configuration/#document-collections
just_the_docs:
  collections:
    # custom collections
    content:
      name: Content
      nav_fold: true
    components:
      name: Components
      nav_fold: true
    experiments:
      name: Experiments
      nav_fold: true
    taxonomies:
      name: Taxonomies
      nav_fold: true

    # default collections (last position(s)) --- do not modify
    tools:
      name: Tools
      nav_fold: true

Even if structuring your documentation in folders does not have limitations, it is strongly recommended to not give names starting with _ for folders placed on the first level under doc-contents since is better to keep this naming convention for collection folders

Home page

Collections are shown on the home page in a dedicated collection section (after the home page header section). The default settings for the home page, collection settings are defined in _data/pageBuildConfig.yml as shown next:

collections_section:
      enabledInHome: true
      except:  # collection name must be the one from _config.yml
      itemsToShow: 4
      collectionStartBtnText: "Start here"
      buttonsClass: "btn-primary"
      buttonsTextClass: "text-light"
    

enabledInHome: the collection section is shown or not in the home page
except: list of collections that must be not shown, given in the form ["posts", "..", ".."]
itemsToShow: number of collection docs to be shown in the list on home page. Most recent documents will be selected.
collectionStartBtnText: the text shown on the button link to the collection entry document (if such entry point is defined)
buttonsClass: the type of the button link to the collection entry document (see Bootstrap buttons)
buttonsTextClass: the type of the text shown on he button link to the collection entry document (see Text colours)

Entry point

A collection can have (or not) a document which is its entry point. In case if this document is defined, when building the side and creating the collection section of the home page, a link button is added to the list of the documents from the collection and points to the collection entry document. The collection entry point configuration is defined in the front_matter of the document which needs to be such an entry point, as shown below, as example:

---
layout: page
title: Content
permalink: /content/intro/
nav_order: 1
start: true
categories: 
tags: 
---

start: if true, the document will be the collection entry point. If false or missing, the document will not be the collection entry point. If more documents are set with start:true, the first one found at the build time will be the collection entry point.
nav_order: not mandatory but recommended. Is the position of the document inside the collection, so it is recommended to be placed on the first position.