# digiDocs Tools

Utility scripts for maintaining the digiDocs repository.

## generate_index.py

Generates `.docs-index.json` - a machine-readable index of all documentation.

### Purpose

Creates a searchable index for joeyking (jk.dbits.ca) and other tools to discover and search documentation without reading every file.

### What it does

1. Scans all `.md` files in the repository
2. Extracts YAML frontmatter metadata (title, description, category, tags)
3. Falls back to extracting title from first heading and description from first paragraph
4. Derives category from folder structure if not specified
5. Generates `.docs-index.json` with all document metadata

### Usage

```bash
# Run manually
python tools/generate_index.py

# Runs automatically via Forgejo Actions when .md files are committed to main
```

### Automation

The `.forgejo/workflows/regenerate-index.yml` workflow automatically:
- Triggers on push to main branch when `.md` files change
- Runs the index generator
- Commits and pushes `.docs-index.json` if it changed

### Metadata Format

Documents should include YAML frontmatter:

```yaml
---
title: Document Title
description: Brief summary for search results
category: services|legal|backup|security|getting-started|products|policies|about
tags: [tag1, tag2, tag3]
---
```

### Index Structure

```json
{
  "version": "1.0",
  "repo": "digiDocs",
  "generated": "2026-01-28T12:00:00Z",
  "doc_count": 73,
  "docs": [
    {
      "path": "Services/Device_Management.md",
      "title": "Device Management",
      "description": "Core device management services and tiers",
      "category": "services",
      "tags": ["device", "services"],
      "audience": "customer"
    }
  ]
}
```

### Requirements

- Python 3.7+
- No external dependencies (uses only standard library)