54de1e33d8
Some checks failed
Regenerate Documentation Index / regenerate-index (push) Failing after 7s
- Improved tag extraction with 60+ digiBandit-specific keywords - Better description extraction (skip metadata, clean markdown) - Added related docs detection based on folder/tags - Added Forgejo Action workflow for auto-regeneration - Added tools/generate_index.py for standalone index generation
74 lines
1.8 KiB
Markdown
74 lines
1.8 KiB
Markdown
# 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)
|