Writing docs

How this site is organised and how to add to it. All content is plain Markdown in the GitHub repository; every push to main rebuilds the site automatically.

Folder layout

index.md                      Home page
docs/
  ditos-erp/
    index.md                  Section landing page (has_children: true)
    getting-started.md        Child page (parent: DiTOS ERP)
    ...                       Add more child pages here
  ditos-loyalty/
  ...
  writing-docs/index.md       This page
_config.yml                   Site settings and theme
_sass/custom/custom.scss      Custom styling

Add a new product

Create a folder under docs/, for example docs/ditos-hr/.
Add index.md with this front matter. nav_order sets the sidebar position.
```
---
title: DiTOS HR
nav_order: 9
has_children: true
---
```
Add the product to the table on the Home page.

Add a page to a product

Create a Markdown file in the product folder with front matter that names the parent:

---
title: User Roles
parent: DiTOS ERP
nav_order: 2
---

Pages sort by nav_order, then alphabetically by title. Pages without a title do not appear in the sidebar.

For a third level (for example, a page under “API” under “DiTOS ERP”), give the middle page has_children: true and add grand_parent: DiTOS ERP to the leaf page.

Make pages easy to read

Callouts highlight what matters. Put the class on the line before a paragraph:

{: .note }
Plain information the reader should notice.

{: .tip }
A shortcut or best practice.

{: .important }
Something that affects correctness.

{: .warning }
Something that can cause data loss or downtime.

This is what a warning looks like.

Table of contents on long pages: add this under the main heading.

## On this page
{: .no_toc .text-delta }

1. TOC
{:toc}

Code blocks get a copy button automatically. Always set the language after the opening fence, for example ```sql.

Images go in assets/images/<product>/ and are referenced with a relative path.

Preview locally (optional)

With Ruby installed:

gem install bundler jekyll
bundle init && bundle add jekyll just-the-docs jekyll-remote-theme
bundle exec jekyll serve

Then open http://localhost:4000.