Structure overview

Understand the structure of dolittle documentation

Structure internally

Documentation lives in our Documentation repository’s Source folder. The 2 main pieces of this folder are content and repositories:

Source/repositories contain submodules to Dolittle repositories. We are moving away from this, please don’t add new submodules.
Source/content is the folder that Hugo uses to render dolittle.io, making it the root of the pages. It contains documentation and symlinks to each Source/repositories submodules Documentation folder.

Defining folder hierarchy on dolittle.io

To add structure (sub-folders) to the content folder and make these visible, Hugo expects an _index.md inside the subfolders. The _index.md files acts as a landing page for the subfolder and should contain a Front Matter section. This defines the title, description, keywords & relative weighting in its parent tree.

---
title: Page Title
description: A short description of the pages contents
keywords: comma, separated, keywords, to, help, searching
author: authorname
weight: 2
---

_index.md files within subfolders should only contain the Front Matter and nothing else unless needed. This makes the subfolder links on the sidebar work as only dropdowns without linking to the content of the _index.md. We prefer this as it makes for a more smooth experience on the site.

You should only have an _index.md file for the uppermost landing page of dolittle.io like Getting started, Contributing etc.

Only create subfolders when needed. Aim for a flat structure.

Last modified June 20, 2023: changes to documentation on documentation (e57c44a)