How to Use AI to Generate Markdown Docs for Your Codebase

You wrote the code. Now you need docs. But not the bloated kind.

The simple, Markdown-based, human-readable kind.

Let’s automate it.

1. What We’re Doing

This isn’t about generating API references or type signatures.

It’s about letting AI help you write readable docs for humans — quick explanations, usage examples, gotchas, etc.

Think README sections, how-it-works.md, or inline guides for contributors.

We’re skipping the GUIs and no-code fluff. This is terminal-friendly, Markdown-native, and works offline once you’ve got it running.

2. What You’ll Need

• An OpenAI API key (or another model you prefer)
• A shell or terminal
• Your codebase (or sample files) ready to go
• A short prompt telling the AI what kind of doc you want

You can write your own prompt or start with something like this:

You are a technical writer. Read the code below and generate a concise Markdown doc that explains:
- What it does
- How to use it
- Any important caveats or examples

Write in a calm, clear tone. Use headings, bullets, and code blocks if needed.

Save that to prompts/gen-docs.txt.

3. Feed It a File

Now pass both the prompt and your code to the model.

Here’s a basic example using curl and OpenAI’s API:

curl https://api.openai.com/v1/chat/completions   -H "Authorization: Bearer $OPENAI_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "'"$(cat prompts/gen-docs.txt code/utils.py)"'"}
    ]
  }' | jq -r '.choices[0].message.content' > docs/utils.md

This takes code/utils.py, sends it with your prompt, and saves the result to docs/utils.md.

4. Make It Reusable

Once you’ve got a template that works, save it and reuse it across your project.

Better yet, automate it. You can:

• Build a CLI wrapper around the OpenAI API
• Feed .py, .js, or .sh files in and pipe Markdown out
• Hook it into a pre-commit hook to generate README updates
• Use jq, awk, or Python to pre-process inputs

Even a tiny script like this can batch your doc generation:

for f in src/*.py; do
  openai api chat.completions.create     --model gpt-4     --messages "$(cat prompts/gen-docs.txt $f)"     > docs/$(basename "$f" .py).md
done

5. Clean It Up Like a Human

AI is helpful, but not perfect.

You’ll still want to: - Skim and trim the output - Fix formatting weirdness - Add links or references - Reword things for your actual audience

Don’t skip this step — you’re still the editor.

If you want to keep your repo maintainable and contributor-friendly, this kind of automation saves hours.

No more neglected docs. No more “we’ll write that later.”

Just clean Markdown, every time you commit.