Where knowledge becomes product

GitHub GitHub last commit CI Workflow GitHub code size in bytes GitHub Issues Total Downloads Monthly Downloads

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:

  1. Plugin configuration, in the website’s services.yaml, under derafu.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).
  2. 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 /pages prefix 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).

On this page

Last updated on 15/11/2026 by Anonymous