[karl-bullock]

Two pages in the 2.x extend sidebar ship with nothing but a heading, and three pages state things about 2.0 that are no longer true. This fills in the first and corrects the second. Every API detail below was read out of flarum/framework@2.x rather than inferred.

The two blank pages

extend/post-types.md contained only # Post Types, and extend/slugging.md only # Model Slugging. Both are listed under Advanced Guides in extendSidebar, so they were reachable, visibly blank pages, and extend/views.md already linked into the slugging one where it mentions $slugManager.

Post Types now covers the type discriminator on posts and what makes an event post different from a comment; building one on AbstractEventPost with a static $type and why content can be treated as an array; MergeableInterface, what saveAfter() receives and what it has to return, and how a pair of opposite events cancels out; registering with Extend\Post; creating the post from a listener through Discussion::mergePost(), including that the post it returns may not be the instance you passed and may no longer exist; the EventPost component with a table of its four overridable methods and the user/username/time variables it injects into the translation; and registering the component with Extend.PostTypes. It points at flarum/lock as a complete worked example, because that extension happens to use every piece.

Model Slugging now covers what a slug driver is, and that adding one gives the admin an option rather than changing every forum; a table of core's five drivers across Discussion and User; the slug_driver_<class> setting and its fallback to default when the stored value names a driver that is no longer registered; writing a SlugDriverInterface and why fromSlug() takes an actor; the round-tripping constraint, and why core's default keeps the ID in the slug; registering with Extend\ModelUrl; making a model of your own sluggable, and why such a model must register a driver under the identifier default (as flarum/tags does for Tag); BatchSlugDriverInterface for resolving many slugs in one query, and checking for it before using it; and labelling your drivers in the admin UI, which needs the static AdminPage.modelLocale and BasicsPage.driverLocale extended, since otherwise the dropdown renders your raw identifier and the heading renders the raw class name.

Three claims 2.0 has outrun

extend/theme.md said a capability does not exist when it does. The page read: "There currently isn't an extender to modify Less variable values in the PHP layer, but this is planned for future releases." Extend\Theme::addCustomLessVariable() does exactly that, and Extend\Settings::registerLessConfigVar() exposes a database setting as a Less variable, which is how core's own @config-primary-color and @config-secondary-color are defined. Theme::addCustomLessVariable's docblock even cross-references the Settings method. None of the Theme extender's four methods were documented anywhere in the docs, so that paragraph is replaced with sections for the custom variable, the setting-backed variable, addCustomLessFunction, and the overrideLessImport / overrideFileSource file overrides. The custom-variable section carries a warning that the returned value is written into the stylesheet verbatim and is not escaped or quoted for you, which is what the extender's own docblock cautions about.

extend/i18n.md contradicted itself about gender. One paragraph credits ICU MessageFormat with handling "pluralization and genderization"; the "Dealing with Gender" section a few lines later said support "will be added in a future version of Flarum". The frontend translator is format-message, a full ICU implementation, and ICU plural is already used throughout core.yml, so select works today. That section now documents it, with a note that Flarum does not store a gender for users so the variable has to come from the extension's own data.

extend/frontend-pages.md quoted code that no longer exists. The DiscussionPageResolver example showed a free getDiscussionIdFromSlug() function whose docblock read "A more robust system will be implemented alongside UTF-8 support in beta 15". In core 2.x that is a canonicalizeDiscussionSlug() method, with a different docblock, and onmatch has changed as well. The snippet now matches core, with a note that being a method is what lets an extension override it, linking to the new slugging page.

Verification

npm run build compiles the English docs with no errors, both new pages render, and Docusaurus's own broken-anchor check reports nothing for the 2.x English docs. Every Flarum\* class reference and every flarum/{common,forum,admin}/... import path in the new pages resolves against the 2.x source.

Not included

I left config.md alone, since #573 is already rewriting it, and its new note that extensions document their own config keys covers the one gap I had found there.

Separately, flarum/realtime is bundled but has no admin-facing documentation on this site, while its README carries a full production setup guide. That needs a decision about shape rather than a guess from me, so I opened #593 for it instead of writing something here.