Where knowledge becomes product
Your content — documentation, FAQs, courses, blogs — is not just text. It’s a valuable asset that can be packaged, reused, and leveraged like a digital product.
derafu/content is a PHP library that turns a directory of Markdown files into a content website: pages, navigation, tags, search and an interface AI agents can call directly. Every plugin adds one content type or one capability on top of the same core.
Two kinds of configuration
Every plugin has, potentially, two independent configuration surfaces, and it is important not to confuse them:
- Plugin configuration, in the website’s
services.yaml, underderafu.content.config.plugins.<name>. This is set once by whoever runs the website (which directory to scan, which URL to call, whether a feature is enabled at all). - Content frontmatter, the YAML block at the top of each Markdown file (
---title: ...---). This is set by whoever writes a specific piece of content (its title, tags, whether it’s a draft, etc.).
Both are documented per plugin, but the frontmatter fields are mostly the same across every content type — see Content frontmatter for the fields shared by all of them. Each plugin’s page only documents what it adds or overrides on top of that shared set.
The configuration sections markdown, plugins, i18n and customFields are maps with string keys. Numeric keys at the root of these sections raise a translatable type error naming the section. Lists inside a section, such as Markdown extensions, keep their numeric indexes.
The class of a plugin
The key of each plugin under plugins is its name, and by default it is the plugin of the package that has that name: docs is Derafu\Content\Plugin\Docs\DocsPlugin, blog is Derafu\Content\Plugin\Blog\BlogPlugin. The option class says another class for it, which has to implement Derafu\Content\Contract\PluginInterface; the rest of the options are the ones of that plugin, and the plugin does not receive class:
parameters:
derafu.content.config:
plugins:
manual:
class: App\Content\ManualPlugin
name: manual
path: resources/content/manual
A plugin whose options are not an object, whose class is not a text, that does not exist or that does not implement PluginInterface is an error that names the plugin. A name without class that is not a plugin of the package is the same error.
A plugin can register routes with the addRoute action received by contentLoaded(). Each route requires string name and path values, and a handler that is a string, an array or a Closure. Optional defaults is a map and methods is a list of strings; missing or null values use empty arrays. Invalid types raise translatable errors identifying the route option.
Content hierarchy
Content types that support nesting (Docs, Academy, FAQ, Pages) build their hierarchy from the filesystem: a subdirectory represents a level of nesting, and it needs a file with the same name as the directory to represent that level itself. For example:
docs/
facturacion.md # Represents the "facturacion" section itself.
facturacion/
anular-dte.md # A child of that section.
Without facturacion.md, the loader has no content item to attach facturacion/anular-dte.md to, and the whole subdirectory is silently skipped — it will not show up in listings, search, or the API export. This is the single most common cause of “my content doesn’t show up.”
Missing content is a 404, not a 500
Requesting a URI that doesn’t exist (or a draft outside a local environment) throws Derafu\Content\Exception\ContentNotFoundException, which is mapped to 404 Not Found — across every content plugin (Academy, Blog, Docs, FAQ, Pages) and Storage attachments alike, since they all resolve through the same ContentRegistryInterface::get(). A draft that isn’t allowed is treated the same way on purpose, so a 403 doesn’t reveal that it exists.
The same goes for a plugin that the website did not enable: the routes of every plugin are registered, so a request to one that is off (for example /sitemap.xml without the sitemap plugin) throws Derafu\Content\Exception\PluginNotFoundException, also mapped to 404. It is still an InvalidArgumentException, so the callers that are not a request, like the tools of MCP, keep catching it.
Service composition
Import the production service configuration:
imports:
- { resource: '../vendor/derafu/content/resources/config/content-services.yaml' }
It imports Renderer and Twig Components’ optional Derafu Twig integration.
Derafu\Content\Provider\ContentTemplatePathProvider contributes only Content’s
resources/templates directory through derafu_twig.template_path_provider.
Twig Components contributes its own templates and component classes. Both use
the shared Twig environment and Renderer services; applications do not need to
redeclare the renderer or copy either package’s template paths.
The application contributes its layout templates through another
TemplatePathProviderInterface. A higher tag priority lets an application
override selected package templates while retaining the other contributions.
Routing services and the application translator remain part of the consuming
application’s composition. Content requests UrlGeneratorInterface and
RouteRegistrarInterface; it does not bind either contract to
RouterInterface. A standalone Derafu application imports Routing’s published
routing-services.yaml (or its filesystem variant), while a Symfony
integration supplies its own generator and registrar. These two capabilities
can be independent services.
For example, a Derafu HTTP application’s config/services.yaml can import:
imports:
- { resource: '../vendor/derafu/http/resources/config/http-services.yaml' }
- { resource: '../vendor/derafu/content/resources/config/content-services.yaml' }
parameters:
derafu.routing.routes: '%routes%'
The HTTP composition supplies the shared standalone router. Load Content’s
route catalogue through the application’s config/routes.yaml:
imports:
- { resource: '../vendor/derafu/content/resources/config/content-routes.yaml' }
Content’s service configuration also requires kernel.project_dir and
kernel.cache_dir from the application. Renderer, Twig and Twig Components
remain shared; Content does not import the HTTP kernel or pipeline itself.
For output formats that need the optional Markdown or PDF engines, install their dependencies and import the corresponding Renderer configurations as well:
imports:
- { resource: '../vendor/derafu/content/resources/config/content-services.yaml' }
- { resource: '../vendor/derafu/renderer/resources/config/renderer-markdown-services.yaml' }
- { resource: '../vendor/derafu/renderer/resources/config/renderer-pdf-services.yaml' }
These imports add engines to the shared renderer. See PDF and Markdown export for the formats supported by Content.
Plugins
- Academy: Course management (course → module → lesson hierarchy).
- API: Bulk JSON export of the content, meant for external indexing/RAG pipelines.
- Blog: Blog management.
- Docs: Documentation management.
- FAQ: FAQ management.
- MCP: Exposes the content as an MCP (Model Context Protocol) server, so AI agents (Claude Code, Claude Desktop, Cursor, etc.) can search and fetch it directly as tools instead of relying on stale training data.
- Pages: Standalone pages management, rendered under a
/pagesprefix by default so it doesn’t conflict with hand-authored flat pages. - Search: Semantic search engine integration, with an optional LLM-based conversational answer (“ask”) grounded on the indexed content.
- Sitemap: XML sitemap of every indexable content item, for search engines.
- Storage: Attachment storage and download management.
Every content item can also be rendered as HTML, Markdown or PDF, on top of the JSON used by the API and MCP plugins — see PDF and Markdown export for what those two add beyond the raw content (video/quiz rendering, bundling a whole section into one file, download buttons on the HTML view).