TL;DR — AI is good at drafting Markdown, but weak prompts usually
produce messy source: wrapper text, broken heading levels, giant tables, and
code fences around the whole document. The practical fix is simple: ask for
Markdown-only output, define the structure you want, do a quick cleanup pass,
then export. That workflow works well with depapel,
especially when the same file may later become PDF or DOCX.
AI-generated notes, specs, and guides usually fail in the same way. The first
draft looks fine in chat, but once you paste it into a real .md file, the
structure is sloppy. The model added "Here is the Markdown", skipped from #
to ###, used a wide table where a list would be easier to read, or forgot the
language tag on a code block. That is when export quality starts to break down.
The good news is that you do not need a complicated prompt library. You just
need a small workflow that keeps the Markdown readable before it ever becomes a
PDF or DOCX.
The workflow that works
Use this order:
- Ask for Markdown only.
- Tell the model exactly what structure to use.
- Prefer compact lists over wide tables unless a table is really needed.
- Do a two-minute cleanup pass before saving or exporting.
- Export only after the Markdown source reads cleanly as plain text.
That sounds basic, but it solves most AI-generated Markdown problems.
What to ask the model for
The best prompt is explicit about both format and shape.
Write the document in Markdown only.
Do not add any intro sentence, wrapper text, or outer code fence.
Use one H1 title.
Use ## for main sections.
Use bullet lists for steps or options.
Use fenced code blocks with a language tag when showing code or config.
Prefer short paragraphs.
Do not use wide tables unless the comparison really needs columns.
That prompt does two important things:
- It removes chatty wrapper text that does not belong in the document.
- It gives the model a document shape that is easy to review and convert.
If you know the destination matters, say that too. For example: "This Markdown
will later be exported to PDF and DOCX, so keep headings, lists, and code
blocks clean."
Why AI Markdown usually breaks at export time
The failure is rarely "the converter is bad." More often, the source document
was noisy.
Common problems:
- Multiple H1s or skipped heading levels.
- A full document wrapped in one giant code fence.
- Tables used for simple lists or checklists.
- Code blocks without language tags.
- Mixed bullet styles and inconsistent spacing.
- Long paragraphs with no section breaks.
Here is a small raw Markdown example that usually converts cleanly:
# Release Notes Draft
## What changed
- Added Git URL import
- Improved PDF table layout
- Export now supports DOCX
## Deployment
```bash
make frontend-deploy
```
## Risks
- Verify large tables on a fresh page
- Check Mermaid diagrams in both PDF and DOCX
The point is not beauty. The point is stable structure.
The cleanup pass you should always do
Before you save the AI draft or send it to a converter, check five things:
- There is only one
# heading.
- The heading levels are in order.
- Lists are actually lists, not fake tables.
- Code blocks have language tags like
bash, json, or python.
- Extra wrapper text is gone.
This pass takes less time than fixing a bad export later.
Where depapel fits
Once the Markdown source is clean, depapel is a good fit
for the export step.
- The same Markdown can become PDF or
DOCX.
- You can use the web app for one-off exports and repeated handoff work.
- Public Git URLs work well when the source already lives in a repository.
This matters because AI-assisted docs often move through several stages:
drafting, review, then delivery. Clean Markdown makes those handoffs much less
painful.
Honest limitations
AI can still generate awkward structure even with a good prompt. depapel helps
with export, but it does not magically turn bad source into a well-written
document.
It is also worth being explicit about what this workflow is not:
- It is not a substitute for editing the content.
- It is not a good reason to keep giant AI-generated tables that should be
rewritten as bullets.
- It does not imply custom Word template automation or advanced publishing
features that depapel does not claim.
The rule to remember
Treat AI as a fast Markdown drafter, not as the final formatter.
Ask for clean structure, do a short cleanup pass, and only then export. If the
Markdown reads well in plain text, it usually has a much better chance of
turning into a clean PDF or DOCX later.
Please enable JavaScript to use depapel.