Support Center & Knowledge base

Managing Sub Folders & Repositories

The content folder is the base for all the content that is created for the documentation solution. The actual contents are pulled from the linked-to repositories as defined in repositories.json. It’s also possible to build out a helper structure to aid with the linking and grouping of documentation across repositories.

Structure

Defining folder hierarchy

To add structure (sub-folders) to the content folder and make these visible, hugo expects an _index.md available with a front-matter section that defines the title, description, keywords & relative weighting in its parent tree.

Note! Only use lower cased folder names.

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

Making structure deployable

By default the contents folder is ignored in the .gitignore file. This is to avoid including symlinks into the repository. You have to manually add your newly added _index.md to git.

Manually add markdown files in content folder

Run the following command from the Source/Hugo folder. Replace with your relevant path

git add content/path/to/_index.md -f

Unignore markdown files in .dockerignore

If the supporting folder structure isn’t in place, the cloning and linking of repositories will fail in the dockerizing process. To avoid this, make sure to explicitly mark the relevant markdown or other static content file as included in .dockerignore

Example of including a sub-folder called tools and its index

!content/tools/_index.md

Content from other repositories

When linking to a repository for the first time, make sure the `Documentation` folder exists, otherwise the symlink will fail, and the solution won't pick up any documentation changes from that repository. Redeploy when the folder exists.

To link to documentation from another repository, add that repository to the repositories.json file located in Source/Hugo . The repository should have a folder named Documentationat its root with its documentation written in markdown.

Example of repositories.json

{
    "https://github.com/dolittle/home.git": {
        "name": "guidelines",
        "path": "contributing/where_to_start"
    },
    "https://github.com/dolittle/learning.git": {
        "name": "getting started",
        "path": ""
    }
}
Parameter Description
name Name of the folder that will be linked to
path Path under content it will be placed

The build.js task iterates over repositories defined in the repositories.json file, and gives them a matching name, and places the link in the relevant sub-folder in the content folder.

The above repositories.json will generate the following output. Note the _index.md files should already be in the content folder:

content
|---_index.md
|---getting started [linked to home/Documentation]
|---contributing
    |---_index.md
    |---where_to_start        
        |---_index.md
        |---guidelines [linked to learning/Documentation]