langgenius/dify-docs: The Docs Repo That Audits Its Own Source

A Mintlify-powered documentation engine where English is canonical, translations are build artifacts, and AI-assisted rules keep the docs glued to the code.

8 min read · langgenius/dify-docs

A black ink editorial scene of a meticulous workbench covered with MDX pages, source files, translated sheets, and a stamped checklist. The image explains that this documentation repo behaves like a control system, not a passive content folder. — The repo works like a test harness for prose. It checks whether the published docs still match the product beneath them.

Key Takeaways

Dify’s docs repo treats English MDX as the canonical layer and translation folders as downstream artifacts, which keeps publication aligned with the product.
Claude Skills and verification scripts turn editorial judgment into repeatable checks, so docs can fail fast instead of drifting quietly.
The navigation is product strategy in disguise, because it mirrors the audiences and adoption paths Dify actually serves.
The real product here is trust, because the repo optimizes for fidelity across code, docs, and translation rather than page count.

The docs repo acts like a test harness

Most documentation repositories store pages. This one enforces a contract. In `langgenius/dify-docs`, the interesting unit is not the article or the page, but the rule that keeps prose, translation, and code from drifting apart.

That is why the repo feels closer to infrastructure than publishing. `docs.json` shapes the site, `writing-guides` governs style, `.claude/skills` codifies editorial behavior, and `verify-env-docs.py` checks whether the docs still match the code they describe.

The `file-preview` API has been available since the integration in Dify, but the corresponding documentation has **not** been updated yet. Please keep this issue open until the docs reflect the new endpoint.

lyzno1, MEMBER · GitHub issue #389

Why Dify needs documentation as infrastructure

Dify is not a single-user library with one happy path. It has product users, self-hosters, and plugin developers, which means the docs have to answer different questions without splitting into separate realities. If the docs drift, each audience feels the break in a different way.

End-users need guidance that matches the product UI.
Self-hosters need deployment detail that matches the running system.
Plugin developers need API and extension docs that stay in lockstep with code.

The docs truth loop shows how a code change becomes documentation, translation, verification, and finally publication.

English is the source, everything else is derivative

The cleanest idea in the repo is also the strictest one. English under `/en` is the source of truth, while `/zh` and `/ja` are generated outputs, not places for ad hoc editing. That choice turns translation into a controlled build step, not a side channel.

This matters because translation is where docs projects usually leak consistency. Dify closes that leak by making the downstream folders feel like artifacts, which keeps the canonical layer small, reviewable, and easier to verify.

A black ink scene of an English manuscript flowing into two printing presses labeled by their output stacks rather than by text banners. A locked gate blocks anyone from editing the translated stacks directly, showing that translation is a derivative build step. — English feeds the system. Chinese and Japanese emerge as outputs, not as alternate sources of truth.

Claude Skills turn editorial policy into executable rules

The most unusual part of the repo is not the docs engine. It is the policy layer around it. The `SKILL.md` files teach the assistant to trace Pydantic models back to OpenAPI and to follow env vars from `api/configs/` through to where they are consumed in the product.

That is a stronger stance than style guidance. It says the docs writer should not just describe the system, but prove the system being described. If the code and the page disagree, the page is not automatically right.

The verifier catches drift before it ships

`verify-env-docs.py` is the clearest example of the repo behaving like quality control. It parses `.env.example`, compares it with MDX tables, normalizes truthy values, and filters out fake defaults so placeholder strings do not look like real configuration.

That sounds small until you see the failure mode it prevents. Without this kind of check, an environment variable can change in code long before the docs catch up, and the mismatch becomes someone else’s support ticket.

A close-up black ink illustration of a jeweler’s loupe comparing a `.env.example` sheet against a documentation table. A thin inspection arm measures names, defaults, and placeholder strings, explaining how the repo verifies configuration docs against source files. — The verifier does not trust memory. It compares the docs to the source files and flags drift as soon as it appears.

The navigation is product strategy

The `docs.json` file quietly reveals how Dify thinks about users. The top-level structure separates `Use Dify`, `Self-host`, and `Develop Plugin`, which is not just information architecture. It is an operational map of how people adopt the product.

That matters because a documentation tree can either mirror internal ownership or mirror the user journey. This repo chooses the second path, which makes the navigation feel less like a sitemap and more like a guide to the business.

Typical OSS docs repo	langgenius/dify-docs
Markdown lives in many folders, and the source of truth is often implicit.	English MDX is canonical, and translated folders are downstream artifacts.
Translation is often mixed with manual edits and local exceptions.	Translation is treated as a generated output with guardrails around it.
Checks usually stop at links and formatting.	Verification scripts compare docs against code, env samples, and placeholder logic.
Style guides are advice for writers.	Claude Skills encode code fidelity and env-var workflows as repeatable rules.
Navigation often follows page ownership or release history.	Navigation mirrors the product’s audiences and adoption paths.
Mismatch can ship quietly until users complain.	Mismatch is supposed to fail fast before publication.
The goal is coverage.	The goal is trust.

What this beats, and where it still depends on discipline

Compared with a normal docs stack, this is more mature. The repo does not just publish content, it checks whether content still deserves to be published. That makes it closer to a control system than a static site.

The catch is that no amount of automation removes the need for maintainers who care about fidelity. The issue about the `file-preview` API not being documented yet is not a bug in the idea. It is the reason the idea exists.

So the real story is not that Dify uses AI to write docs. It is that Dify uses policy, scripts, and AI to keep the docs honest. That is the difference between a docs site and a documentation system.