Skip to content

Docs_Model_Docs

@api

Docs_Model_Docs — the zero-config, multi-source documentation engine.

There is NO manifest. A COLLECTION is just "a directory of doc files" (+ an _index.md), and a collection can draw from MORE THAN ONE directory — aggregated automatically from three sources:

  1. PLATFORM content — each subfolder of the module's content// dir (Guide, CMS, …).
  2. MODULE docs — each ACTIVE module that ships a <module>/docs/<locale>/ folder becomes its own collection (slug = module name). Self-documenting modules: drop a docs/ folder and it appears; deactivate the module and it's gone. (Toggle with docs.modules.scan.)
  3. GENERATED reference — var/docs-generated/<locale>/<slug>/, produced on the instance by bin/build-reference.php (docblocks → tiger:doc pages). A per-instance BUILD ARTIFACT, never committed. It merges INTO a matching collection (adding a "Reference" section to a module's docs) or stands up its own (the platform reference collection). Hand-written pages win.

Every file self-describes in a leading HTML comment (invisible when rendered):

VISIBILITY splits one engine into two surfaces: the public site (/docs, guests) shows public docs; the in-admin help center shows admin docs (how to operate a module). A file's visibility defaults to its collection's _index visibility, which defaults to public.

Everything is fronted by Docs_Model_Index — a per-server, fingerprint-invalidated build cache that spans all source dirs (see that class). DB docs remain the resolve-time override tier.

Methods

__construct()

__construct()

Resolve the module's content/ directory for the multi-source scan.

rebuildIndex()

rebuildIndex($locale = 'en')

Force a rebuild of this server's cached index (admin "Rebuild index" / deploy warm).

  • $locale string — the content locale to rebuild

Returns array — the freshly built index payload

collections()

collections($locale = 'en', $visibility = self::VIS_PUBLIC)

Collections visible on a surface, sorted: [ ['slug','title','order','vis'], … ].

  • $locale string — the content locale
  • $visibility string — the target surface (public|admin)

Returns array — the visible collections, ordered

collectionSlugs()

collectionSlugs($locale = 'en', $visibility = self::VIS_PUBLIC)

Collection slugs visible on a surface (for the controller's URL split).

  • $locale string — the content locale
  • $visibility string — the target surface (public|admin)

Returns array — the visible collection slugs

tree()

tree($locale = 'en', $collection = self::DEFAULT_COLLECTION, $base = '/docs', $visibility = self::VIS_PUBLIC, $default = self::DEFAULT_COLLECTION)

The nested nav tree for a collection on a surface — visibility-filtered + url-stamped. $default is the prefix-less collection ('guide' public, '' admin → everything namespaced).

  • $locale string — the content locale
  • $collection string — the collection slug to build the tree for
  • $base string — the base path each node URL is stamped under
  • $visibility string — the target surface (public|admin)
  • $default string — the prefix-less collection slug

Returns array — the nested, url-stamped nav tree

resolve()

resolve($slug, $locale = 'en', $orgId = '', $collection = self::DEFAULT_COLLECTION, $visibility = self::VIS_PUBLIC)

Resolve a doc → normalized array or null (→ 404): ['slug','collection','title','html','headings','format','visibility','source'] A page whose visibility doesn't match the requesting surface returns null (a public URL can't serve an admin doc, and vice-versa). Empty slug = the collection's _index (landing).

  • $slug string — the URL slug (may be nested; empty = the collection landing)
  • $locale string — the content locale
  • $orgId string — the tenant/org id for the DB override tier
  • $collection string — the collection slug
  • $visibility string — the requesting surface (public|admin)

Returns ?array — the normalized doc array, or null (→ 404)

search($q, $locale = 'en', $visibility = self::VIS_PUBLIC, $limit = 8)

Search a surface's docs. Ranked hits: [ ['slug','collection','title','section','snippet','score'], … ].

  • $q string — the search query
  • $locale string — the content locale
  • $visibility string — the target surface (public|admin)
  • $limit int — the maximum number of hits to return

Returns array — the ranked hits