AI Documentation Playbook

This playbook provides a standardized workflow and prompt templates for prompting AI coding assistants to generate documentation for your applications.

Whenever you create a new application or service, you can give your AI assistant the prompt below. The AI will inspect your code and produce a comprehensive markdown documentation page that fits right into this Just-the-Docs portal.

1. How the Documentation System Works

Location: All documentation markdown files are saved under custom_images/portal/docs/apps/ (or docs/infrastructure/).
Front Matter: Every document must begin with Jekyll front matter specifying title, parent, and nav_order.
Automatic Compilation: The Docker build compiles all Markdown files with syntax highlighting, search indices, and callouts into the Portal static site.
Homepage Link: When adding a new app, also add a card in custom_images/portal/_layouts/home.html pointing to https://<app>.babdelka.com and /docs/apps/<app>/.

2. Master AI Prompt Template

Copy and paste this prompt when asking an AI assistant to document a service:

I need you to create a complete Just-the-Docs documentation page for my project "[APP_NAME]".

The target file must be created at:
custom_images/portal/docs/apps/[APP_SLUG].md

Ensure the file starts with this Jekyll front matter:
---
layout: default
title: [APP_NAME]
parent: Applications
nav_order: [NAV_ORDER_NUMBER]
permalink: /docs/apps/[APP_SLUG]/
---

Please structure the documentation with the following standard sections:

1. Overview
   - Summary of purpose and key functionality.
   - Live URL (https://[APP_SLUG].babdelka.com).
   - Technology stack (Languages, frameworks, databases, libraries).

2. Architecture & Components
   - Architecture overview or ASCII/Mermaid diagram.
   - Container configuration (base image, exposed ports, non-root user).
   - Key runtime environment variables and secrets.

3. Kubernetes Deployment & GitOps
   - Namespace and Deployment spec.
   - Gateway API HTTPRoute definition and hostnames.
   - Resource requests and limits (CPU/Memory).
   - Storage/PVC requirements if persistent.

4. API Endpoints or Usage Guide
   - Core HTTP endpoints (method, path, request/response payload examples).
   - Or UI workflow if it is primarily a web interface.

5. Operations, Troubleshooting & Maintenance
   - How to check pod logs (`kubectl logs -n [NAMESPACE] -l app=[APP]`).
   - How to restart (`kubectl rollout restart deployment/[APP] -n [NAMESPACE]`).
   - Common errors and how to resolve them.

3. Just-the-Docs Markdown Conventions

Callout Boxes

Just-the-Docs supports colorful callout alerts:

{: .note }
> This is a general informative note.

{: .tip }
> This is a tip or best practice advice.

{: .important }
> This is critical information that must not be missed.

{: .warning }
> This is a warning about potential failure modes or data loss.

Code Blocks & Syntax Highlighting

Always specify the programming or format language (yaml, bash, javascript, python, json):

```bash
# Check service logs
kubectl logs -n md2pdf -l app=md2pdf --tail=50 -f
```

Action Buttons

To render styled buttons for links:

[Open Live Application](https://md2pdf.babdelka.com){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
[View Source Code](https://gitlab.babdelka.com){: .btn .fs-5 .mb-4 .mb-md-0 }

4. Registering the Service on the Homepage

When adding documentation for a new app, register it on the portal homepage so users can launch it directly:

Open custom_images/portal/_layouts/home.html.
Duplicate an existing <div class="service-card" ...> block.
Update:
- data-category: ai, devops, tools, or infra.
- service-name: App Title.
- service-url-sub: Domain hostname (e.g. myapp.babdelka.com).
- service-desc: Brief 1-2 sentence description.
- service-tags: Technology pills.
- btn-launch href: https://myapp.babdelka.com.
- btn-docs href: /docs/apps/myapp/.
Run build.sh to update the portal image!